Upgrading from Prior Versions

 

Sunaccess 8.6 employs major design changes from previously released versions. The package now uses the common Sunbelt file access functions in the SunFHDll library and a revised calling syntax. Users upgrading from previous versions of Sunaccess should consider the following:

 

  1. In previous versions of Sunaccess, the user was responsible for defining a file control block before any functions could be called. This is no longer required of the user and is preformed by the Prepare and Open functions. The value returned by the Open and Prepare functions is a Sunaccess handle. That value is then used as input to subsequent functions and identifies the target file. The file control blocks allocated within the Prepare and Open functions are released by the Close functions.

 

An example of an indexed file open would be:

 

SA_FH fh;

fh = SA_IsiOpen( "myfile.isi", 10, SA_SHARE )

 

  1. The function definition headers of the Sunaccess routines now require the specification of the length of any string parameters passed. In previous versions, the user was required to pass a null terminated string. In the above example, "myfile.isi" is a string that contains the target file name. The second parameter (10) defines the length of the string not including any null terminating value. This change simplifies access from languages that do not use null terminated strings.

    2.  

  2. The record length returned by the Read functions is the length of the record plus one. This change was required to distinguish a zero length record from the end of file indication (0). An example of a Read function that properly checks for an error or an end of file is:

 

retval = SA_IsiRead( fh, buffer, buffer_length, key, key_length );

if( retval < 0 )

{

    printf( "Isam read error code: %d\n", retval );

    exit( 1 );

}

else if( retval == 0 )

{

    printf( "Record not found.\n" );

}

else

{

    printf( "Record: %s", buffer );

}

 

  1. The entry point names have been changed to a more consistent and unique format. For example, in Sunaccess 8.5, the ISAM read key sequential function name was "isiReadKS". In version 8.6, it has become "SA_IsiReadKS".

  2. Sunaccess now returns the same error codes as the Sunbelt runtimes for I/O (I) errors. The error numbers are reported as a negative value to make detection simpler. In previous versions, a "-13" returned from the ISAM read function (isiRead) indicated the target file had not been previously opened. The error code returned now is "-5". Using this value, the user can reference the Sunbelt Runtime Reference I/O error listing for an "I05" error which reports "I/O operation attempted on an unopened file."

  3. A complete category of text file functions have been added. These functions compliment the ISAM and AAM functions and provide new capabilities such as update and delete functions.

  4. New general purpose functions have been added that include file erasing, renaming, flushing and other functions. End of file handing and error subcode reporting functions are also provided.

  5. The Sunaccess functions now allow access to data files via the Sunbelt Data Manager. To open a file located on a Sunbelt Data Manager server, specify:

 

if ((fh = SA_IsiOpen("mastf8mr.isi|64.246.11.321:502", 26, SA_SHARE)) < 0)

{

    printf("Open error code = %d, fh );

    exit(1);

}

 

where "64.246.11.321" is the IP number and "502" is the port number of the Sunbelt Data Manager. Optionally, the user can use a Managed File Descriptor to open the file:

 

if ((fh = SA_IsiOpen("mastf8mr.mfd", 12, SA_SHARE)) < 0)

{

    printf("Open error code = %d", fh );

    exit(1);

}

 

The MFD is created using the Sunbelt "makemfd" utility and specifies the location of the server and other parameters.

 


Sunaccess Reference Dealing with Pointers in Cobol Sample C Program