SE SetTransmittalName

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE SetTransmittalName

extern SE_Return_Code
SE_SetTransmittalName
(
	SE_Transmittal		transmittal_in,	(notes)
const	char	*	new_transmittal_name	(notes)
);

Definition

Given an SE_Transmittal handle, set (or modify) the formal transmittal name associated with the transmittal. This function can be used to supply the FIRST name for a transmittal opened using SE_OpenTransmittalByFile(), or to modify the name of a transmittal that was previously named or opened using SE_OpenTransmittalByName().

See the comments for the function SE_ResolveTransmittalName() for details on the format of the transmittal name. For other information regarding the SEDRIS URN namespace, consult the SEDRIS documentation set.

CAUTION
While setting the transmittal name is desirable in many cases, care should be taken when invoking this function. The API is not responsible for managing configuration and changing control for the transmittal being modified. Calling this function will PERMANENTLY change the transmittal name associated with the file containing the SEDRIS transmittal. Be sure this is the desired result BEFORE calling this function.

Returns

SE_RET_CODE_SUCCESS and the transmittal name is set.

SE_RET_CODE_FAILURE and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS set if valid parameters were passed in and the transmittal name was successfully set.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_INVALID_TRANSMITTAL_NAME set if the new_transmittal_name parameter did not specify a name that was valid according to the formal SEDRIS namespace. See the comment in the SE_ResolveTransmittalName() function description about the nature of the validation done.

SE_STAT_CODE_INVALID_ACCESS_MODE set if transmittal_in was opened in read-only mode.

SE_STAT_CODE_INACTIONABLE_FAILURE set if the call fails for any other reason.

Parameters Notes

transmittal_in

 handle to the transmittal for which the name should
    be set.

new_transmittal_name

 a pointer to character array specifying a valid
    transmittal name in the formal SEDRIS namespace.  This parameter is
    validated only based upon the structured format of the name string.
    That is, the sub-fields within the string are only checked for proper
    structure (character set, delimiters, etc.) and are NOT checked for
    consistency with namespace delegation rules, and proper use of
    transmittal versioning.

SE_RET_CODE_SUCCESS	and the transmittal name is set.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

SE_STAT_CODE_INVALID_TRANSMITTAL_NAME	set if the new_transmittal_name parameter did not specify a name that was valid according to the formal SEDRIS namespace. See the comment in the SE_ResolveTransmittalName() function description about the nature of the validation done.
SE_STAT_CODE_INVALID_ACCESS_MODE	set if transmittal_in was opened in read-only mode.
SE_STAT_CODE_INACTIONABLE_FAILURE	set if the call fails for any other reason.