Function Name: Open Transmittal By Name

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_NULL_REQUIRED_PARAMETER - and *transmittal_out_ptr is left unaltered, if either the transmittal_name or transmittal_out_ptr is NULL.

SE_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_UNRESOLVED_TRANSMITTAL - and *transmittal_out_ptr is set to NULL, if the API could not resolve the transmittal_name to a file location.

SE_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_INVALID_ACCESS_MODE - and *transmittal_out_ptr is set to NULL, if

1. 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.
2. if create or update mode was requested and the API implementation does not support the write capability.

SE_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_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_FAILURE - and *transmittal_out_ptr is set to NULL, if

1. dynamic binding is specified at compile time, but the shared library for the specified API implementation cannot be found,
2. dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library,
3. any problems not covered by the above are encountered while finding or opening the SEDRIS transmittal specified by the name parameter.

Prototype

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.