SE OpenTransmittalByName

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE OpenTransmittalByName

extern SE_Status_Code
SE_OpenTransmittalByName
(
const	char		transmittal_name[],	(notes)
const	char		implementation_identifier[],	(notes)
	SE_Access_Mode		access_mode,	(notes)
	SE_Transmittal	*	transmittal_out_ptr	(notes)
);

Definition

Opens a SEDRIS transmittal for access based on the mode specified. This function specifies the SEDRIS transmittal to be opened using the formal transmittal name of the SEDRIS transmittal. The formal name of the SEDRIS transmittal is resolved automatically based on the process described for the function SE_ResolveTransmittalName().

Returns

SE_STAT_CODE_SUCCESS and a handle to the newly opened SEDRIS transmittal is copied into *transmittal_out_ptr, if valid parameters were passed in and the name was a valid transmittal name that the API could resolve and access.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and *transmittal_out_ptr is left unaltered, if either the transmittal_name or transmittal_out_ptr is NULL.

SE_STAT_CODE_INVALID_TRANSMITTAL_NAME and *transmittal_out_ptr is set to NULL, if the transmittal_name did not specify a name that was valid according to the format of the SEDRIS namespace.

SE_STAT_CODE_UNRESOLVED_TRANSMITTAL and *transmittal_out_ptr is set to NULL, if the API could not resolve the transmittal_name to a file location.

SE_STAT_CODE_TRANSMITTAL_UNACCESSIBLE and *transmittal_out_ptr is set to NULL, if the file location of the resolved transmittal name was not accessible by the API. This could occur if (1) the transmittal was opened for read-only or update and the resolved file location did not exist, or (2) if the resolved file location specified a non-local file and the API had no transport mechanism for accessing the remote file.

SE_STAT_CODE_INVALID_ACCESS_MODE and *transmittal_out_ptr is set to NULL, if

the resolved file location was found, but the security permissions of the underlying system (OS / filesystem) prohibited access to the file in the mode specified. This could occur if the access mode specified was create or update and the file was marked read-only, or if no access was permitted for the account running the application.

if create or update mode was requested and the API implementation does not support the write capability.

SE_STAT_CODE_UNSUPPORTED_FORMAT and *transmittal_out_ptr is set to NULL, if the resolved transmittal name referenced a format that is not supported by the implementation(s) of the SEDRIS API linked to the application.

SE_STAT_CODE_OUT_OF_MEMORY and *transmittal_out_ptr is set to NULL, if *transmittal_out_ptr could not be allocated, or if there is insufficient memory for any other part of the process of opening the transmittal.

SE_STAT_CODE_FAILURE and *transmittal_out_ptr is set to NULL, if

dynamic binding is specified at compile time, but the shared library for the specified API implementation cannot be found,

dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library,

any problems not covered by the above are encountered while finding or opening the SEDRIS transmittal specified by the name parameter.

Parameters Notes

transmittal_name

 the formal name of the SEDRIS transmittal to be opened.

implementation_identifier

 identifies the API implementation
    to use when opening this file.  If the specified API can't open the
    given file location then the API will return a status code indicating
    why it could not be opened.  If implementation_identifier is NULL, then
    the API will try to open the given SEDRIS transmittal based on the
    extension of the file location.

    See also SE_GetImplementationIdentifier().

access_mode

 the mode (read-only, create, update, etc.) that the
     SEDRIS transmittal should be opened in.

transmittal_out_ptr

 a pointer to the SE_Transmittal from the user.
    The *transmittal_out_ptr value will be initialized by this function.

SE_STAT_CODE_SUCCESS	and a handle to the newly opened SEDRIS transmittal is copied into *transmittal_out_ptr, if valid parameters were passed in and the name was a valid transmittal name that the API could resolve and access.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *transmittal_out_ptr is left unaltered, if either the transmittal_name or transmittal_out_ptr is NULL.
SE_STAT_CODE_INVALID_TRANSMITTAL_NAME	and *transmittal_out_ptr is set to NULL, if the transmittal_name did not specify a name that was valid according to the format of the SEDRIS namespace.
SE_STAT_CODE_UNRESOLVED_TRANSMITTAL	and *transmittal_out_ptr is set to NULL, if the API could not resolve the transmittal_name to a file location.
SE_STAT_CODE_TRANSMITTAL_UNACCESSIBLE	and *transmittal_out_ptr is set to NULL, if the file location of the resolved transmittal name was not accessible by the API. This could occur if (1) the transmittal was opened for read-only or update and the resolved file location did not exist, or (2) if the resolved file location specified a non-local file and the API had no transport mechanism for accessing the remote file.
SE_STAT_CODE_INVALID_ACCESS_MODE	and *transmittal_out_ptr is set to NULL, if the resolved file location was found, but the security permissions of the underlying system (OS / filesystem) prohibited access to the file in the mode specified. This could occur if the access mode specified was create or update and the file was marked read-only, or if no access was permitted for the account running the application. if create or update mode was requested and the API implementation does not support the write capability.
SE_STAT_CODE_UNSUPPORTED_FORMAT	and *transmittal_out_ptr is set to NULL, if the resolved transmittal name referenced a format that is not supported by the implementation(s) of the SEDRIS API linked to the application.
SE_STAT_CODE_OUT_OF_MEMORY	and transmittal_out_ptr is set to NULL, if transmittal_out_ptr could not be allocated, or if there is insufficient memory for any other part of the process of opening the transmittal.
SE_STAT_CODE_FAILURE	and *transmittal_out_ptr is set to NULL, if dynamic binding is specified at compile time, but the shared library for the specified API implementation cannot be found, dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library, any problems not covered by the above are encountered while finding or opening the SEDRIS transmittal specified by the name parameter.