STATEL API - Europa€¦ · 112:API:Insufficient disk space (cfr SNN.ISF) # 259:INCORP: could not...

Copyright (C) S. A. Eeckels, 2000

STATEL API

Table of Contents

Foreword 0

Part I STATEL API: functions description 2

................................................................................................................................... 21 Administrative functions

.......................................................................................................................................................... 2StatelGetLocalSNN - Get the name of the local STATEL installation

.......................................................................................................................................................... 2StatelBuildSNNList - Build a list of valid SNNs

.......................................................................................................................................................... 2StatelUnlock - Unlock a locked STATEL tuple

.......................................................................................................................................................... 3S_VERSION - return a pointer to a string containing the STATEL version number

................................................................................................................................... 32 Basic functions

.......................................................................................................................................................... 3S_INITIALIZE - Initialize STATEL

.......................................................................................................................................................... 5S_STARTVFS - Enable STATEL VFS access

.......................................................................................................................................................... 5S_EXEC - Execute a STATEL process on the remote host

................................................................................................................................... 63 VFS related functions

.......................................................................................................................................................... 6Directory handling

......................................................................................................................................................... 6S_CHDIR - Change the Current Working Directory

......................................................................................................................................................... 7S_MKDIR - Create a VFS directory file

......................................................................................................................................................... 8S_RMDIR - Remove a VFS directory file

......................................................................................................................................................... 8SS_WILDCARD - Handle wildcards in a STATEL directory

.......................................................................................................................................................... 11File handling

......................................................................................................................................................... 11S_OPEN - Open a Statel VFS file

......................................................................................................................................................... 13S_READ - Read a sequence of bytes from a VFS file

......................................................................................................................................................... 13S_WRITE - Write a sequence of bytes to a VFS file

......................................................................................................................................................... 14S_UNLINK - Remove a file from the VFS

......................................................................................................................................................... 15S_SEEK - Move the file pointer in a STATEL file

......................................................................................................................................................... 16S_FCNTL - STATEL file control functions

......................................................................................................................................................... 17S_STAT, S_FSTAT, S_ISTAT - Obtain the status of a VFS file

......................................................................................................................................................... 18S_CLOSE - Close a Statel VFS file

................................................................................................................................... 194 Messaging functions

.......................................................................................................................................................... 19S_GETMESSAGE - Retrieve a message from the message queue

.......................................................................................................................................................... 21S_PUTMESSAGE - Send a message

................................................................................................................................... 215 Error handling functions

.......................................................................................................................................................... 21S_ERRORCODE - return the STATEL error code

................................................................................................................................... 246 Document version

Index 0

STATEL APII


STATEL API: functions description 2


1 STATEL API: functions description

1.1 Administrative functions

1.1.1 StatelGetLocalSNN - Get the name of the local STATEL installation

SYNOPSISchar *StatelGetLocalSNN(void)

DESCRIPTIONThis function is used to retrieve the local SNN. It can be used when no STATEL sessionhas been started (through calling S_INITIALIZE() ). Application developpers should usethis function, and refrain from parsing the SNN.ISF file themselves, as both the file andits layout are implementation dependent.

1.1.2 StatelBuildSNNList - Build a list of valid SNNs

SYNOPSISint StatelBuildSNNList(int (callBack)(char *snn, char *dir))

DESCRIPTIONThis function is used to obtain the list of valid SNNs and their associated tuple directories.It calls function callBack for each valid SNN, in the order they appear in the mainconfiguration file ( SNN.ISF ), and passes both the SNN and the tuple directory to thecallback. It can be used to load SNNs into arrays, or check items (locks) in the tupledirectory.EXAMPLE

/* For each remote SNN */ StatelBuildSNNList(LoadSNN); if ( !SNNindex ) { fprintf(stderr, "%s\n", S_ERROR()); fprintf(ouf,"SNNindex : %d\n", SNNindex); fflush(ouf); return -4; } for ( idx=0; idx<SNNindex; idx++ ) if ( snn == NULL || strcmp(snn,SNNarray[idx]) == 0 ) CheckSNN(SNNarray[idx],ouf); fflush(ouf); return 0;

Figure 1.

1.1.3 StatelUnlock - Unlock a locked STATEL tuple

SYNOPSIS

STATEL API3


int StatelUnlock(char *snn)

DESCRIPTIONThis function is used to unlock a tuple. Tuples can remain inaccessible when a STATELsession is interrupted without S_TERMINATE being called.NOTEThis function should only be used when it is absolutely certain that the STATEL session isno longer active, as unlocking could seriously upset the proper functioning of an activetuple.

1.1.4 S_VERSION - return a pointer to a string containing the STATEL versionnumber

SYNOPSIS#include "apistatel.h"...char *S_VERSION()

DESCRIPTIONReturn a pointer to a (static) string containing the current STATEL version number. Asthis version number is unlikely to change during the life of the program, it can be usedwithout copying...

1.2 Basic functions

1.2.1 S_INITIALIZE - Initialize STATEL

SYNOPSIS#include "apistatel.h"...SStatus *S_INITIALIZE(statelNickName)char *statelNickName;

int S_TERMINATE();

DESCRIPTIONS_INITIALIZEThe primitive is used to start the STATEL dialog. It returns a pointer to a structure givingstatus information about the requested STATEL tuple. The routine returns a null pointer [(SStatus\*)0 ] on failure, and sets the StErrorNumber variable. The ERRORNUMBERmacro can be used to extract the effective error code, which can be one of the followingvalues:

ST_ALREADY_INITIALIZED: A successful call to S_INITIALIZE has already been made.ST_NO_MEMORY: A fatal error occurred using dynamic memory (PANIC).ST_CANNOT_LOCK: A LOCK file cannot be created (PANIC).ST_NO_CONTROL_FILE: Cannot find the tuple control file (PANIC).ST_NO_MASTER:



Cannot find the STATEL config file.ST_INVALID_DESTINATION: StatelNickNameis not a valid destination.ST_CONFIG_ERROR: A configuration error has been detected.ST_NO_SEQUENCE: The tuple control file lacks sequence number information.ST_NO_TA: The tuple control file lacks Agent information.ST_INVALID_TA: An Agent entry is neither SYNC nor ASYNC.

Figure 8.

Please note that the S_ERRORCODE() routine should be used to access the globalvariable StErrorNumber under the MS-Windows environment. This routine can also beused in the Unix and MS-DOS environments, and its use is encouraged.S_TERMINATEThis primitive is used to terminate the STATEL dialog. All S_OPEN ed files are closed (asa service to the programmer). Messages that were read during the session are discarded.The routine returns 0 on success, -1 otherwise. The StErrorNumber variable is set, andthe ERRORNUMBER macro can be used to extract the effective error code, which can beone of the following:

ST_NOT_ACTIVE: No successful call to S_INITIALIZE has been madeST_NO_CONTROL_FILE: Cannot find the tuple control file (PANIC).ST_CANNOT_UPDATE_SEQUENCE: Error trying to increment sequence number info.

Figure 9.

DATA STRUCTURESThe following figure shows the data structures used by the routines:

typedef struct smsgQueue /* STATEL Message Queue structure */{ long messageNumber; char messageId[5]; long messageLength; int messageRead; struct smsgQueue *nextMessage; struct smsgQueue *previousMessage; long __location;} SMsgQueue;

typedef struct /* STATEL status structure */{ long localSequence; long remoteSequence; long lastAck; /* Last PDU ack'ed by remote */ long activeMessages; /* Number of messages */

STATEL API5


SMsgQueue *firstMessage; /* Pointer to first message */ SMsgQueue *lastMessage;} SStatus;These structures are intended to be read-only, and should not bechanged by the program. Doing so could crash the application.

Figure 10.

SEE ALSOS_EXEC()S_GETMESSAGE()

1.2.2 S_STARTVFS - Enable STATEL VFS access

SYNOPSIS#include "apistatel.h"...int S_STARTVFS()

DESCRIPTIONThis routine must be called to enable access to the VFS. Before S_STARTVFS() , only themessage primitives are accessible. If S_INITIALIZE() has not yet been called, the routinereturns -1 and sets the STATEL error code to ST_NOT_ACTIVE . Else it returns 0. TheSTATEL error code can be retrieved with S_ERRORCODE() or transformed in an errormessage through S_ERROR() . In the Unix and MS-DOS implementations, the error codeis also available in the StErrorNumber global variable.

1.2.3 S_EXEC - Execute a STATEL process on the remote host

SYNOPSIS#include "apistatel.h"...int S_EXEC(programName, argv, stdVector)char *programName;char *argv[];char *stdVector[];

DESCRIPTIONThe STATEL program programName is executed on the remote host. argv is a pointer tothe parameter list, the last element should be NULL. stdVector contains the (optional)names of the STATEL VFS files to whichstdin, stdoutand stderr have to be redirected.The remote execution request is queued, and its results can ONLY be obtained after theexecution of S_TERMINATE() and a subsequent S_INITIALIZE() (ie. in a new STATELsession).RETURN VALUESThe call returns 0 on success, -1 otherwise. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.

ST_NOT_ACTIVE:S_INITIALIZE() has not yet been called.



ST_NO_MEMORY:A fatal error occurred using dynamic memory (PANIC).

Figure 5.

FILES"Statel program definition sample file"[Commands]#Statel_command=local_command (without parameters)statells=/bin/ls

SEE ALSOS_INITIALIZES_ERRORS_TERMINATE

NOTEThis command is obsolescent on Windows platforms.

1.3 VFS related functions

1.3.1 Directory handling

1.3.1.1 S_CHDIR - Change the Current Working Directory

S_GETCWD - Get the Current Working Directory

SYNOPSIS#include "apistatel.h"...int S_CHDIR(directoryName, key)char *directoryName;char *key;

char *S_GETCWD()

DESCRIPTIONThe S_CHDIR() primitive is used to set the current working directory to directoryName

. If the directory was created with a key , this key should be given for thecall to succeed.

When S_INITIALIZE() returns, the current working directory is set to "/" (the root of theVFS).

The S_GETCWD() function returns the value of the current working directory for theactivated STATEL tuple.

RETURN VALUESThe S_CHDIR() call returns 0 if successful. If not, it returns -1 and sets the STATEL error

variable.The S_GETCWD() call returns a pointer to a string containing the current working directory

upon success, or NULL on failure, setting the STATEL error variable. Its valuecan be retrieved with S_ERRORCODE() or transformed in an error messagethrough S_ERROR() . In the Unix and MS-DOS implementations, the errorcode is also available in the StErrorNumber global variable.

STATEL API7


ST_NOT_ACTIVE:S_INITIALIZE has not been successfully called.

ST_NOT_STARTED:S_STARTVFS has not been called.

V_INTERNAL_ERROR:A breakdown in STATEL processing (PANIC).

V_INVALID_KEY:The keyis incorrect.

V_NOT_A_DIRECTORY:The file name given is not a VFS directory.

V_FILE_IN_PATH:one of the elements of the path is a file.

V_NO_SUCH_FILE:the directory does not exist.

Figure 2.

SEE ALSOS_OPEN

1.3.1.2 S_MKDIR - Create a VFS directory file

SYNOPSIS#include "apistatel.h"...int S_MKDIR(fileName, key)char *fileName;char *key;

DESCRIPTIONThe primitive is used to create a subdirectory in the VFS. The fileName can be absolute orrelative, but should not end with a '/'.The key parameter can be used to implement a simple form of security, by associating apass string with the directory. Files in such a directory cannot be accessed if the key isnot known.RETURN VALUESThe function returns 0 on success, -1 otherwise. StErrorNumber is set to indicate thecause of the error (note that StErrorNumber is guaranteed to be zero when the functionexecutes successfully). The function S_ERRORNUMBER() can also be used to retrieve theerror number, and should be used in the MS-Windows environment.

ST_NOT_ACTIVE:No successful call to S_INITIALIZE has yet been made.

ST_NOT_STARTED:S_STARTVFS has not been called

ST_NO_MEMORY:Dynamic memory management problem (PANIC).

V_INVALID_FILENAME:Badly formed file name

V_NO_SUCH_FILE:Invalid path (or member)

V_FILE_EXISTS:



The file/directory already existsST_WRITE_ERROR:

Access to one of the STATEL OS files has been refused

Figure 11.

1.3.1.3 S_RMDIR - Remove a VFS directory file

SYNOPSIS#include "apistatel.h"...int S_RMDIR(directoryName, key)char *directoryName;char *key;

DESCRIPTIONThe primitive is used to remove a subdirectory from the VFS.RETURN VALUESThe call returns 0 on success, -1 otherwise. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.


V_INVALID_FILENAME:Invalid file name

V_NO_SUCH_FILE:file fileNamedoes not exist.

V_DIRECTORY_NOT_EMPTY:The directory is not empty (first remove all files)

V_INVALID_KEY:The keyis not correct

ST_WRITE_ERROR:Write problem to STATEL OS files.

Figure 14.

1.3.1.4 SS_WILDCARD - Handle wildcards in a STATEL directory

SS_WILDCARD - Handle wildcards in a STATEL directory

SYNOPSIS#include "apistatel.h"...char *SS_WILDCARD(pathName, key, type)char *pathName;char *key;int type;

STATEL API9


DESCRIPTIONThis function takes a pathName in the STATEL VFS and returns a string with the first fullpath name matching the specification. If pathName contains wildcard characters they areexpanded to match the entries in the VFS directory structure. If type is equal to 0,wildcards follow the Unix shell convention, else if it is equal to 1, Unix full regularexpressions are recognised. When type is 2, all the file names below the directoryspecified in PathName are returned. When PathName is set to the root ('/'),SS_WILDCARD walks the complete directory tree recursively. Repeated calls to thisfunction with the same pathName or a NULL pointer result in all possible matches beingreturned. When all possibilities are exhausted, the function returns a null pointer.UNIX SH WILDCARDSWithout the -F option, characters will be interpreted as follows:1. charmatches itself, unless it is a special character (metacharacter): ? \ [ ] *2. "?"Matches any singlecharacter.3. "*"Matches any sequence of zero or more characters.4. "[set]"matches one of the characters in the set. If the first character in the set is "^", itmatches any character NOT in the set. A shorthand S-E is used to specify a set ofcharacters S up to E, inclusive. The special characters "]" and "-" have no specialmeaning if they appear as the first characters in the set.examples: match:

[a-z] any lowercase alpha

[!]-] any char except ] and -

[!A-Z] any char except uppercase alpha

[a-zA-Z] any alpha

5. "\"matches the character following it.REGULAR EXPRESSIONS1. charmatches itself, unless it is a special character (metacharacter): . \ [ ] + ^ $ *2. "."matches any character.3. "\"matches the character following it, except when followed by a left or right round bracket,a digit 1 to 9 or a left or right angle bracket. (see [7], [8] and [9]) It is used as anescape character for all other meta-characters, and itself. When used in a set ([4]), it istreated as an ordinary character.4. "[set]"matches one of the characters in the set. If the first character in the set is "^", itmatches a character NOT in the set. A shorthand S-E is used to specify a set ofcharacters S up to E, inclusive. The special characters "]" and "-" have no specialmeaning if they appear as the first chars in the set.examples: match:

[a-z] any lowercase alpha

[^]-] any char except ] and -



[^A-Z] any char except uppercase alpha

[a-zA-Z] any alpha

5. "*"any regular expression form [1] to [4], followed by closure char (*) matches zero ormore matches of that form.6. "+"same as [5], except it matches one or more.7. "$...$"a regular expression in the form [1] to [10], enclosed as $form$ matches what formmatches. The enclosure creates a set of tags, used for [8] and for pattern substitution.The tagged forms are numbered starting from 1.8. "\n"a \ followed by a digit 1 to 9 matches whatever a previously tagged regular expression([7]) matched.9. "\<...\>"a regular expression starting with a \< construct and/or ending with a \> construct,restricts the pattern matching to the beginning of a word, and/or the end of a word. Aword is defined to be a character string beginning and/or ending with the characters A-Za-z 0-9 and _. It must also be preceded and/or followed by any character outside thosementioned.10. "xy"a composite regular expression xy where x and y are in the form [1] to [10] matches thelongest match of x followed by a match for y.11. "^ $"a regular expression starting with a ^ character and/or ending with a $ character,restricts the pattern matching to the beginning of the line, or the end of line [anchors].Elsewhere in the pattern, ^ and $ are treated as ordinary characters.EXAMPLEThe following figure shows an example program using the SS_WILDCARD function toprovide a simple STATEL directory listing using wildcard characters.

int#ifdef __STDC__main(int argc, char *argv[])#elsemain(argc, argv)int argc;char *argv[];#endif{ char *retVal;

if (S_INITIALIZE(argv[1]) == NULL) { uError(0, "S_INITIALIZE"); S_TERMINATE(); exit(1); }

S_STARTVFS(); while ((retVal = SS_WILDCARD(argv[2], "", 0)) != NULL)

STATEL API11


{ printf("Matched: %s\n", retVal); } S_TERMINATE();}

Figure 21.

SEE ALSOregex

ACKNOWLEDGEMENTSThe regular expression matching code was taken from the public domain, and waswritten by: Ozan S. Yigit (oz) Dept. of Computer Science York UniversityANSI prototypes and regex.h added by Mark Russell, UKC.ANSI function declarations by Stefaan A. Eeckels, Eurostat.

1.3.2 File handling

1.3.2.1 S_OPEN - Open a Statel VFS file

SYNOPSIS#include "apistatel.h"...int S_OPEN(fileName, mode, key)char *fileName;int mode;char *key;

DESCRIPTIONVFS file filename in the VFS is opened or created, depending on mode . This can be READ, WRITE , WRONLY RDWR , or APPEND (see below). The key is used to implement aform of access control; if a file has been created with a specific key , any subsequentaccess requires the same key to be presented. Key can be used to restrict S_OPEN ing ofthe directory, or its use as a current directory ( S_CHDIR ), but notto restrict the usage ofthe directory in a file path, provided that the terminal file is accessible (ie. it has no keyor a valid key has been provided with the S_OPEN call)."File creation"The use of WRITE or APPEND with a non-existing file name causes the file to be created.If mode is APPEND , the existing file attributes are maintained (the creator remains whatit was, and the creation sequence is unchanged); when it is WRITE , the file is deletedand re-created."Files without local copyThese files are created through the use of the WRONLY mode. STATEL doesn't store alocal copy of the file, so actions requiring a local copy (such as appending to, modifying,or reading from the file) are not allowed. Strictly speaking the file has become a write-once object. At the remote party's end, the file becomes read-only (it cannot beappended to or modified, because the originator lacks the copy required to representthese actions)."Return value"The routine returns the STATEL file handle (a small integer between 0 (inclusive) and the



maximum number of open STATEL files). When an error occurs, the routine returns -1and the STATEL error code is set to an appropriate error code. The following error codescan be returned:

ST_NOT_ACTIVE:S_INITIALIZE has not been successfully called.

ST_NOT_STARTED:S_STARTVFS has not been called.

ST_NO_MEMORY:A dynamic memory operation failed (PANIC).

ST_NO_CHANNELS:Too many VFS files have been opened.

V_WRITE_TO_DIR:An attempt was made to open a VFS directory in write/append mode.

V_INVALID_KEY:The key provided to open the file is incorrect.

V_FILE_IN_PATH:One of the non-terminal components of a path is a file.

V_NO_SUCH_FILE:The file does not exist (or is still a partial fileand cannot be opened at present).

V_READONLY_FILE:The file was created as a write-only file by theremote party and cannot be opened in the requestedmode (WRITE, APPEND).

V_WRITEONLY_FILE:The file was created as a write-only file and cannotbe opened in the requested mode (READ, APPEND).

V_NO_ROOT_DIR:Cannot open the VFS root directory (PANIC).

V_INTERNAL_ERROR:Something went wrong with the VFS management (PANIC).

Figure 12.

The uError routine can be used to print a (language dependent) error message, and theS_ERROR primitive can be used to incorporate the error message in a custom errorhandling routine. The error code can be retrieved with S_ERRORCODE() , and in the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable."NOTE"The following alternative constants can be used as equivalents for the mode constantsdefined above:VBST_READ READVBST_WRITE WRITEVBST_APPEND APPENDVBST_WRONLY WRONLYVBST_RDWR RDWR

"SEE ALSO"

S_ERROR

STATEL API13


S_CHDIRS_CLOSES_ERRORCODE

1.3.2.2 S_READ - Read a sequence of bytes from a VFS file

SYNOPSIS#include "apistatel.h"...long S_READ(fileHandle, buffer, transferSize)int fileHandle;char *buffer;long transferSize;

DESCRIPTION transferSize bytes are read into buffer from the file accessed through fileHandle(obtained from a preceding S_OPEN call) at the current location of the file pointer. Afterthe operation, the pointer points to the byte following the last byte read.RETURN VALUESThe call returns the number of bytes actually read from the file (this can be less than therequested number if End-Of-File is encountered while reading). On EOF the functionreturns 0, and when an error occurs, it returns -1. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable. The ERRORNUMBER( StErrorNumber ) macro (defined throughapistatel.h) can be used to obtain the effective STATEL error code.NOTES1.The actual number of bytes that can be read depends on the host Operating System. On16-bit MS-DOS compilers, the maximum number of bytes would be 64k (the contents ofan unsigned int). On 32-bit Unix machines, it will be a lot more, but always a positivevalue. The typedef IOsize is set to the maximum allowable block size, and can be used incasts when calling the routine.2.The composite error code contains both the STATEL module number and the STATEL errorcode of the last STATEL error.SEE ALSOS_ERRORCODE

1.3.2.3 S_WRITE - Write a sequence of bytes to a VFS file

SYNOPSIS#include "apistatel.h"...long S_WRITE(fileHandle, buffer, transferSize)int fileHandle;char *buffer;long transferSize;

DESCRIPTION transferSize bytes are written from buffer to the file accessed through fileHandle



(obtained from a successful S_OPEN() call) at the current location of the file pointer.After the operation, the pointer points to the byte following the last byte written.RETURN VALUESThe call returns the number of bytes actually written to the file (this can be less than therequested number if a disk full condition is encountered while writing), or a negativevalue indicating an error condition. The STATEL error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.

ST_NOT_ACTIVE:No successfull call to S_INITIALIZE has yet been made

ST_NOT_STARTED:S_STARTVFS has not been called

ST_FILE_NOT_OPEN:The handle does not reference an open VFS file

"errno":The OS error number

Figure 20.

SEE ALSO

S_ERRORCODE

1.3.2.4 S_UNLINK - Remove a file from the VFS

S_RENAME - Rename a file in the VFS

SYNOPSIS#include "apistatel.h"...int S_UNLINK(fileName, key)char *fileName;char *key;

int S_RENAME(fileName, newFileName, key)char *fileName;char *newFileName;char *key;

DESCRIPTIONS_UNLINKThe file fileName is removed from the VFS. The name can be relative to the currentdirectory (see S_CHDIR ) or absolute .S_RENAMEFile fileName is renamed to newFileName , if the key matches the file's creation key.RETURN VALUESReturns 0 if successfull, -1 otherwise. The STATEL error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable, but its use is deprecated.

STATEL API15



ST_NOT_STARTED:No successful call to S_STARTVFS has yet been made.

V_INVALID_FILENAME:Invalid file name.

V_NO_SUCH_FILE:file fileNamedoes not exist.

V_DIRECTORY_NOT_EMPTY:The directory is not empty (first remove all files).

V_INVALID_KEY:The keyis not correct.

ST_WRITE_ERROR:Write problem to STATEL OS files.

Figure 19.

SEE ALSOS_CHDIR

1.3.2.5 S_SEEK - Move the file pointer in a STATEL file

SYNOPSIS#include "apistatel.h"...long S_SEEK(fileHandle, offset, whence)int fileHandle;long offset;int whence;

long S_TELL(fileHandle)int fileHandle;

DESCRIPTIONS_SEEKThe file pointer is moved to a new position in the file. This can be absolute (whence ==SEEK_SET), relative to the end of the file (whence == SEEK_END), or the currentlocation (whence == SEEK_CUR). Subsequent access (read or write) will take place fromthe new location. It is impossible to move the file pointer beyond the end of a file openedfor reading only. Seeking beyond the end of a file opened for writing or update causeszero bytes to be inserted between the previous End-Of-File and the new position. With afile opened for RDWR (read/write, or update), an S_SEEK must always be issued betweencalls to S_WRITE() and S_READ() .S_TELLReturns the current file pointer for the VFS file.RETURN VALUESThe routines return -1 on error, S_SEEK returns 0 on success, whereas S_TELL returnsthe (positive) displacement in the file. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.



ST_NOT_ACTIVE:No successful call to S_INITIALIZE has yet been made

ST_FILE_NOT_OPEN:The file handle does not reference an open file

"errno":A system error code

Figure 15.

EXAMPLESThe following example shows the use of S_SEEK and S_TELL :

/* *** Call S_WRITE */if (S_WRITE(handle, "12345678901234567890", 20L) != 20L){uError(0, "S_WRITE");}

/* *** Call S_SEEK */if (S_SEEK(handle, 0L, SEEK_SET) != 0){uError(0, "S_SEEK");}

/* *** Call S_READ */if (S_READ(handle, buffer, 20L) != 20L){uError(0, "S_READ");}else{buffer[20] = '';DPRINT1(1, "Read data [%s]", buffer);}

/* *** Call S_TELL */DPRINT1(1, "We're at %ld", S_TELL(handle));

Figure 16.

1.3.2.6 S_FCNTL - STATEL file control functions

SYNOPSIS#include "apistatel.h"...int S_FCNTL(char *name, int command, ...)

DESCRIPTIONThis primitive is used to control attributes of the STATEL files. Currently, its only use is tocontrol the visibility of partial files. .H1 "Show partial files" .H2 "FormatS_FCNTL("file",

STATEL API17


ST_FCNTL_PARTIAL);S_FCNTL("file", ST_FCNTL_COMPLETE);.H2 "Usage When a call to S_STAT() returns the value V_INCOMPLETE_FILE , a call toS_FNCTL() with the ST_FCNTL_PARTIAL flag will allow the file to be opened ordeleted.When access to the partial file is no longer necessary, the function should becalled with the ST_FCNTL_COMPLETE flag to restore normal STATEL behaviour.RETURN VALUEWhen no errors occur, the function returns 0. Otherwise, it returns -1 and theS_ERRORCODE()function can be used to retrieve the effectiveerror.ST_BAD_PARAMETER: Invalid command code used.

NOTEThis call circumvents a protection mechanism in STATEL; please make sure that theeffect is desirable.

1.3.2.7 S_STAT, S_FSTAT, S_ISTAT - Obtain the status of a VFS file

SYNOPSIS#include "apistatel.h"...int S_STAT(fileName, key, stat)char *fileName;char *key;SFileStatus *stat;

int S_FSTAT(fileHandle, stat)int fileHandle;SFileStatus *stat;

int S_ISTAT(inode, key, stat)long inode;SFileStatus *stat;

DESCRIPTIONThe structure pointed to by stat is filled with status information pertaining to fileName(for S_STAT ) the open file identified by fileHandle (for S_FSTAT), or the file defined byinode inode (for F_ISTAT ). Note that for S_STAT and S_ISTAT , the key must bepresented if the call is to succeed.STRUCTURESThe following figure gives the layout of the SFileStatus structure:

typedef struct sfileStatus{

long size;long creationSequence;long modificationSequence;long remoteModificationSeq;long accessSequence;long remoteAccessSequence;long links;char type;char creator;



time_t sta_mtime;time_t sta_ctime;time_t sta_atime;

} SFileStatus;

Figure 17.

RETURN VALUESThe routines return 0 when successful, -1 otherwise. The STATEL error code can beretrieved with S_ERRORCODE() or transformed in an error message through S_ERROR() .In the Unix and MS-DOS implementations, the error code is also available in theStErrorNumber global variable.

V_NO_SUCH_FILE: The file does not exist.V_INVALID_KEY: The key presented in the call does not match the key in the VFS.ST_NO_CHANNELS: There are too many open VFS files and S_STAT cannot open the file.V_FILE_IN_PATH: One of the components of the path name is not a directory.V_INTERNAL_ERROR: The descent of the VFS directory tree went badly wrong (PANIC)V_NO_ROOT_DIR: Cannot find the STATEL root directory (PANIC)ST_NO_MEMORY: The memory management routines went badly wrong (PANIC)

Figure 18.

NOTES_ISTAT will return the information on the file even when the key is incorrect. S_STATdoes not return information when the key is incorrect; the contents of the structure willbe unchanged, and should not be relied upon.

1.3.2.8 S_CLOSE - Close a Statel VFS file

SYNOPSIS#include "apistatel.h"...int S_CLOSE(handle)int handle;

DESCRIPTIONEXAMPLESThe file previously S_OPEN ed is closed. All data is written to the VFS, and the applicationcan no longer access the file. handle should have been obtained from a successful call toS_OPEN .RETURN VALUESThe routine returns 0 when successful, -1 otherwise. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.

STATEL API19


ST_NOT_ACTIVE:No successful call to S_INITIALIZE has been made.

ST_NOT_STARTED:S_STARTVFS has not yet been called.

ST_FILE_NOT_OPEN:The handle does not correspond to an open file.

Figure 3.

SEE ALSOS_OPENS_TERMINATE

1.4 Messaging functions

1.4.1 S_GETMESSAGE - Retrieve a message from the message queue

SYNOPSIS#include "apistatel.h"...int S_GETMESSAGE(messageNumber, messageBuffer)long messageNumber;char *messageBuffer;

DESCRIPTIONRetrieve message messageNumber from the message queue. The message is copied inarea pointed to by messageBuffer which must have been provided or allocated by theuser. Upon execution of S_TERMINATE() , the message is removed from the queue. Thestructure returned by S_INITIALIZE() can be used to examine the message types anddetermine the messageNumber , and the required size of the messageBuffer .RETURN VALUEThe function returns zero on success. If an error occurs, it returns -1 and sets the STATELerror code, which can be retrieved with S_ERRORCODE() or transformed in an errormessage through S_ERROR() . In the Unix and MS-DOS implementations, the error codeis also available in the StErrorNumber global variable. The ERRORNUMBER macro can beused to extract the effective error code, which can be:

ST_NOT_ACTIVE: A successful call to S_INITIALIZE()has not yet been made.ST_INVALID_MESSAGE: messageNumberis not a valid message.ST_NO_MEMORY: An unexpected error occured using dynamic memory (PANIC).

Figure 6.

NOTESThe routine does not return a string (ie. the last character is not necessarily a zero). Ifthe user wants to print the message, she should add the zero herself, and make sure thatthe message is indeed a printable string.If the message is too large to fit in the bufferprovided, the program could crash.EXAMPLE



The following code fragment shows how the information returned by S_INITIALIZE() canbe used to retrieve and print messages.

/* *** Establish STATEL session */ if ((ssp = S_INITIALIZE(nickName)) == (SStatus *)0) { uError(0, argv[0], "SNN=%s", nickName); exit (1); }

if (verboseFlag) { printf("Number of messages= %ld\n", ssp->activeMessages); }

/* *** Read and print the STATEL messages */ if (ssp->activeMessages != 0) { /* *** Loop through all the header structures */ for (msgHead = ssp->firstMessage; msgHead != (SMsgQueue *)0; msgHead =msgHead->nextMessage) { if (verboseFlag) { printf("Message # %ld, ID %s, length %ld\n", msgHead->messageNumber, msgHead->messageId, msgHead->messageLength); }

/* *** Message of required type? */ if (!strcmp(msgHead->messageId, messageType)) { /* *** Allocate the buffer space */ char *messageBuffer = (char *)calloc(1L, msgHead->messageLength+1); S_GETMESSAGE(msgHead->messageNumber, messageBuffer);

/* *** Make sure the message is a string before printing it */ *(messageBuffer+msgHead->messageLength) = '\0'; fprintf(stdout, "%s\n", messageBuffer); free(messageBuffer); } } /* while */ } /* if */

Figure 7.

SEE ALSOS_INITIALIZES_ERROR

STATEL API21


1.4.2 S_PUTMESSAGE - Send a message

SYNOPSIS#include "apistatel.h"...int S_PUTMESSAGE(messageId, messageSize, messageBody)char *messageId;long messageSize;unsigned char *messageBody;

DESCRIPTIONSend a message to a remote application. The messageId is returned in the remotemessageList (see S_INITIALIZE() ).RETURN VALUESThe function returns 0 on success, -1 otherwise. The error code can be retrieved withS_ERRORCODE() or transformed in an error message through S_ERROR() . In the Unixand MS-DOS implementations, the error code is also available in the StErrorNumberglobal variable.

ST_NOT_ACTIVE:A successful call to S_INITIALIZE()has not yet been made.

Figure 13.

1.5 Error handling functions

1.5.1 S_ERRORCODE - return the STATEL error code

S_ERROR - return a pointer to a (multi-language) plain-text error message for STATEL

SYNOPSIS#include "apistatel.h"...ErrorCode S_ERRORCODE()

char *S_ERROR()

DESCRIPTION S_ERRORCODE() returns the value of the last STATEL error. The code is comprised of amodule number (MODCLASS), and the effective error code. Each module in STATEL hasits own number, so the error code can be used to determine where the error occured. TheERRORNUMBER macro can be aplied to the return value of the S_ERROR() call to obtainthe effective error number shown in the table below. The ERRORCLASS macro extractsthe module number from the error code. S_ERROR() eturns a STATEL or system error message corresponding to the value ofStErrorNumber (the global STATEL error variable). STATEL error messages are prefixedwith the version number, the STATEL error number and a colon (cfr the file formatbelow); system messages do not have an error number. The MODCLASS information inStErrorNumber is not used by this routine (the uError() function can be used to printMODCLASS ).The STATEL error description is taken from the appropriate error file in the STATEL Base



Directory. The value of the LANG environment variable is used to select the file for theappropriate language, by appending its value to the base name of the file (eg. the file forthe ENglish language becomes ERRCODE.EN ).Please note that the error file can contain comments starting with '#' or ';'.FILESThe figure below gives the current content of the English error message file ERRCODE.EN.

#This line changes the headers from their default values#Only applicable to uError()Indication=MESSAGE,MODULE ,PR.INFO,#Error messages start here1:API:No master file2:API:Invalid destination SNN3:API:No control file4:API:Sequence missing - Resend request queued6:API:User not authorised7:API:Format error in PDU8:API:Error while opening message body file9:API:Error while opening message header file10:API:Mismatch in sequence between ISC.ID and ISC.TR30:API:STATEL not yet initialized31:API:Invalid STATEL message32:API:STATEL already initialized33:API:Transfer Agent specification missing34:API:Transfer Agent Entry Error40:API:VFS not started (with S_START)41:API:Fatal memory allocation error42:API:Fatal error updating Config file43:API:Invalid receiveTransitDirectory51:API:No such VFS file52:API:VFS File already exists53:API:Invalid VFS filename54:API:Component of path name is a VFS file55:API:VFS Directory not empty56:API:Invalid security key57:API:Attempting to write to a directory58:API:Missing or unreadable inode file59:API:No VFS root directory60:API:File store busy61:API:S_START already executed62:API:No STATEL program list file63:API:Internal Error64:API:Not a directory66:API:Cannot open write-only file for reading67:API:Cannot open read-only file for writing101:API:Bad function parameter102:API:No match103:API:Write error104:API:No channels available105:API:File not open106:API:STATEL in use (LOCK file present)107:API:Configuration error108:API:STATELBASEDIR not absolute

STATEL API23


112:API:Insufficient disk space (cfr SNN.ISF)#259:INCORP: could not read receiveTransitDirectory#85:TMX400: Local ORNAME error#263:tmftp:No user ID specified or known for this host362:tmftp:Invalid password for this user/host combination256:tmftp:Formally incorrect remoteFileName entry.257:tmftp:Cannot access sourceFile.258:tmftp:Incorrect entry in one of the tmftprc files260:tmftp:Cannot fork the ftp command261:tmftp:Cannot open the log file262:tmftp:The slave ftp process died mysteriously263:tmftp:No user specified (-u option or USER= entry)264:tmftp:Cannot stat the rc file265:tmftp:rc file vulnerable (readable by group or world)266:tmftp:Cannot cd to local destination directory267:tmftp:Too many wild cards on the command line.268:tmftp:MS-DOS command line too long354:tmftp:Missing parameter or option356:tmftp:Cannot connect to the remote host357:tmftp:Cannot logon with this user/password358:tmftp:Did not receive a valid ftp prompt359:tmftp:Error on issuing a CD command360:tmftp:Error during file transfer361:tmftp:Could not set connection to binary (image) mode363:tmftp:A password is required but not given (-p option)364:tmftp:The account was not accepted (-a option)365:tmftp:The quit command was not acknowledged#402:tmmapi:Cannot connect to mailbox403:tmmapi:Cannot disconnect from mailbox404:tmmapi:Error attempting to send message405:tmmapi:Error reading message406:tmmapi:Error receiving PDU407:tmmapi:Unknown recipient408:tmmapi:Cannot initialise MAPI.DLL409:tmmapi:Error writing log file410:tmmapi:Insufficient memory411:tmmapi:Configuration file not found#501:tmasync:Formally incorrect remoteFileName entry.502:tmasync:Cannot access sourceFile.503:tmasync:Incorrect entry in the tmasynrc file505:tmasync:Cannot open the log file508:tmasync:No user ID specified or known for this host509:tmasync:Cannot stat the tmasynrc file511:tmasync:Cannot cd to local destination directory599:tmasync:Missing parameter or option601:tmasync:Cannot connect to the remote host602:tmasync:Cannot logon with this user/password604:tmasync:Error on issuing a CD command



605:tmasync:Error during file transfer606:tmasync:Could not set connection to binary (image) mode607:tmasync:Invalid password for this user/host combination608:tmasync:A password is required but not given

Figure 4.

RETURN VALUEThe routine returns either a pointer to a string, or a null pointer. In the latter case, itcould not obtain sufficient memory to process the error file(s). A message to this effectwill be printed to the standard error device.NOTEThe MODCLASS is the individual module number which generated the STATEL error. It isuseful for debugging and locating errors and/or problems.

1.6 Document version

Version number: 3.7.0Last update on: May 15, 2000Author name: Stefaan Eeckels

STATEL API - Europa€¦ · 112:API:Insufficient disk space (cfr SNN.ISF) # 259:INCORP: could not...

Documents

Transcript of STATEL API - Europa€¦ · 112:API:Insufficient disk space (cfr SNN.ISF) # 259:INCORP: could not...