SA_Config

The SA_Config function allows an application to change and set keywords settings that control the operations of the SA_DLL32 dll. This means that a Sunaccess program can get or set the settings for runtime keywords without using keywords in the 'sunacces.ini' control file.

int SA_Config ( u32 KeyValue, u32 ConfigValue, u8 *Buffer, u32 BuffLen );

KeyValue: Identifies the specific keyword control. This value also identifies whether a get or set operation is being executed for the keyword.
ConfigValue: This parameter is an input value that may be used when setting a keyword state.
Buffer: This parameter can be used both as an input and an output. This parameter is always a u8 pointer to a buffer that the calling logic has allocated and initialized. This buffer can contain input data when setting a keyword and may be contain output data when getting a keyword.
BuffLen: This parameter is an input u32 value that identifies the byte size for the data in the 'Buffer' parameter when it is used as an input parameter. The BuffLen value identifies the maximum buffer size when the the Buffer parameter is used for output.

Note the following:

The function return integer value may indicate an error or success of the function. In some cases, the return value indicates the number of characters returned to the calling logic in the Buffer parameter.

Value	Meaning
0	success
+nn	success and value depends on KeyValue.
-nn	error as described in Sunaccess Error keywords.

The KeyValue control values can be specified with one of the following values:

Control	Value	Control	Value
GET_PLB_CHECKFILE2GB	0	SET_PLBWIN_W33RETRY	19
SET_PLB_CHECKFILE2GB	1	GET_PLBWIN_XPIO	20
GET_PLB_CHKDRN	2	SET_PLBWIN_XPIO	21
SET_PLB_CHKDRN	3	GET_PLB_OPENUSEIP	22
GET_PLB_COPYFILEBUFFSZ	4	SET_PLB_OPENUSEIP	23
SET_PLB_COPYFILEBUFFSZ	5	GET_PLB_PREPUSEIP	24
GET_PLB_DPTFILENAME	6	SET_PLB_PREPUSEIP	25
SET_PLB_DPTFILENAME	7	GET_PLB_DMALTIP	26
GET_PLB_EOR	8	SET_PLB_DMALTIP	27
SET_PLB_EOR	9	GET_PLB_PATH	28
GET_PLB_FNC	10	SET_PLB_PATH	29
SET_PLB_FNC	11	GET_PLB_AAMUPPER	30
GET_PLB_LOCKIO	12	SET_PLB_AAMUPPER	31
SET_PLB_LOCKIO	13	GET_PLB_PREP87	32
GET_PLB_NDUP	14	SET_PLB_PREP87	33
SET_PLB_NDUP	15	GET_PLB_RDCLR	34
GET_PLB_OPENABS	16	SET_PLB_RDCLR	35
SET_PLB_OPENABS	17	GET_SA_PRE87B	101
GET_PLBWIN_W33RETRY	18	SET_SA_PRE87B	102

The following KeyValue control values use the function parameters as described below. In each of the tables, the following table values are defined as:

Req: The KeyValue is always required and it has a value as defined in the note (2.) description.
NA: The SA_Config parameter is not used and is not applicable.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_CHECKFILE2GB	0/1/-nn	Req	NA	NA	NA
GET_PLB_CHKDRN	0/1/-nn	Req	NA	NA	NA
GET_PLB_DPTFILENAME	0/1/-nn	Req	NA	NA	NA
GET_PLB_FNC	0/1/-nn	Req	NA	NA	NA
GET_PLB_LOCKIO	0/1/-nn	Req	NA	NA	NA
GET_PLB_NDUP	0/1/-nn	Req	NA	NA	NA
GET_PLB_OPENABS	0/1/-nn	Req	NA	NA	NA
GET_PLBWIN_W33RETRY	0/1/-nn	Req	NA	NA	NA
GET_PLBWIN_XPIO	0/1/-nn	Req	NA	NA	NA
GET_PLB_PREP87	0/1/-nn	Req	NA	NA	NA
GET_PLB_RDCLR	0/1/-nn	Req	NA	NA	NA
GET_SA_PRE87B	0/1/-nn	Req	NA	NA	NA

Where:

0/1/-nn: The returned value can be a zero, one, or an error value. The '-nn' value in this case indicates an error has occurred.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_CHECKFILE2GB	0/-nn	Req	0/1	NA	NA
SET_PLB_CHKDRN	0/-nn	Req	0/1	NA	NA
SET_PLB_DPTFILENAME	0/-nn	Req	0/1	NA	NA
SET_PLB_FNC	0/-nn	Req	0/1	NA	NA
SET_PLB_LOCKIO	0/-nn	Req	0/1	NA	NA
SET_PLB_NDUP	0/-nn	Req	0/1	NA	NA
SET_PLB_OPENABS	0/-nn	Req	0/1	NA	NA
SET_PLBWIN_W33RETRY	0/-nn	Req	0/1	NA	NA
SET_PLBWIN_XPIO	0/-nn	Req	0/1	NA	NA
SET_PLB_PREP87	0/-nn	Req	0/1	NA	NA
SET_PLB_RDCLR	0/-nn	Req	0/1	NA	NA
SET_SA_PRE87B	0/-nn	Req	0/1	NA	NA

Where:

0/-nn: The returned value can be either a zero or an error value. The '-nn' value in this case indicates an error has occurred.
0/1: The input value for the ConfigValue parameter is either a 0 or 1. In this case, any non-zero value can be used.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_COPYFILEBUFFSZ	nn/-nn	Req	NA	NA	NA

Where:

nn/-nn: The returned value is either the current PLB_COPYFILEBUFFSZ value or it is an error value returned as a negative value.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_COPYFILEBUFFSZ	0/-nn	Req	n>1024	NA	NA

Where:

0/-nn: The returned value is either a zero that indicates the new PLB_COPYFILEBUFFSZ has been set or a negative value is returned to indicate that an error has occurred.
n>1024: The input value for the ConfigValue must be greater than 1024.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_EOR	eorId/-nn	Req	NA	NA	NA

Where:

eorId/-nn: The returned value is either an 'eorId' value or it is an error value. The expected 'eorId' values can be one of the following values:

EOR Type	Value
CFG_EOR_CR	1
CFG_EOR_CR_NOAUTO	2
CFG_EOR_LF	3
CFG_EOR_LF_NOAUTO	4
CFG_EOR_CRLF	5
CFG_EOR_CRLF_NOAUTO	6
CFG_EOR_LFCR	7
CFG_EOR_LFCR_NOAUTO	8

See the description of PLB_EOR for more details.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_EOR	0/-nn	Req	eorId	NA	NA

Where:

0/-nn: The returned value can be either zero that indicates that the PLB_EOR keyword was set successfully or a negative value is returned to indicate an error.
eorId: The input ConfigValue parameter must be one of the 'eorId' values as described for the GET_PLB_EOR keyword control.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_OPENUSEIP	nn/-nn	Req	NA	bufPtr	maxSize

Where:

nn/-nn: The returned value can be either the number of bytes that have been stored into the output buffer or it is a negative value that indicates an error has occurred. A returned value of zero in this case indicates that the PLB_OPENUSEIP buffer contains zero bytes.
bufPtr: The Buffer input parameter is a pointer to a buffer that is to receive the PLB_OPENUSEIP data.
maxSize: The maximum number of bytes that can be stored into the bufPtr buffer.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_OPENUSEIP	0/-nn	Req	NA	bufPtr	maxSize

Where:

0/-nn: The returned value can be either a zero that indicates that the PLB_OPENUSEIP was successfully set or it is a negative value that indicates that an error has occurred.
bufPtr: This is a u8 pointer to a buffer that contains the input data to be stored for the PLB_OPENUSEIP keyword. If the bufPtr is NULL, the PLB_OPENUSEIP buffer is cleared.
bufSize: This value identifies how many bytes of data are provided in the input buffer and is to be stored for the PLB_OPENUSEIP keyword. If the bufSize value is zero, the PLB_OPENUSEIP buffer is cleared.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_PREPUSEIP	nn/-nn	Req	NA	bufPtr	maxSize

Where:

nn/-nn: The returned value can be either the number of bytes that have been stored into the output buffer or it is a negative value that indicates an error has occurred. A returned value of zero in this case indicates that the PLB_PREPUSEIP buffer contains zero bytes.
bufPtr: The Buffer input parameter is a pointer to a buffer that is to receive the PLB_PREPUSEIP data.
maxSize: The maximum number of bytes that can be stored into the bufPtr buffer.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_PREPUSEIP	0/-nn	Req	NA	bufPtr	maxSize

Where:

0/-nn: The returned value can be either a zero that indicates that the PLB_PREPUSEIP was successfully set or it is a negative value that indicates that an error has occurred.
bufPtr: This is a u8 pointer to a buffer that contains the input data to be stored for the PLB_PREPUSEIP keyword. If the bufPtr is NULL, the PLB_PLBUSEIP buffer is cleared.
bufSize: This value identifies how many bytes of data are provided in the input buffer and is to be stored for the PLB_PREPUSEIP keyword. If the bufSize value is zero, the PLB_PREPUSEIP buffer is cleared.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_DMALTIP	nn/-nn	Req	NA	bufPtr	maxSize

Where:

nn/-nn: The returned value can be either the number of bytes that have been stored into the output buffer or it is a negative value that indicates an error has occurred. A returned value of zero in this case indicates that the PLB_DMALTIP buffer contains zero bytes.
bufPtr: The Buffer input parameter is a pointer to a buffer that is to receive the PLB_DMALTIP data.
maxSize: The maximum number of bytes that can be stored into the bufPtr buffer.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_DMALTIP	0/-nn	Req	NA	bufPtr	maxSize

Where:

0/-nn: The returned value can be either a zero that indicates that the PLB_DMALTIP was successfully set or it is a negative value that indicates that an error has occurred.
bufPtr: This is a u8 pointer to a buffer that contains the input data to be stored for the PLB_DMALTIP keyword. If the bufPtr is NULL, the PLB_DMALTIP buffer is cleared.
bufSize: This value identifies how many bytes of data are provided in the input buffer and is to be stored for the PLB_DMALTIP keyword. If the bufSize value is zero, the PLB_DMALTIP buffer is cleared.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_PATH	nn/-nn	Req	NA	bufPtr	maxSize

Where:

nn/-nn: The returned value can be either the number of bytes that have been stored into the output buffer or it is a negative value that indicates an error has occurred. A returned value of zero in this case indicates that the PLB_PATH buffer contains zero bytes.
bufPtr: The Buffer input parameter is a pointer to a buffer that is to receive the PLB_PATH data.
maxSize: The maximum number of bytes that can be stored into the bufPtr buffer.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_PATH	0/-nn	Req	NA	bufPtr	maxSize

Where:

0/-nn: The returned value can be either a zero that indicates that the PLB_PATH was successfully set or it is a negative value that indicates that an error has occurred.
bufPtr: This is a u8 pointer to a buffer that contains the input data to be stored for the PLB_PATH keyword. If the bufPtr is NULL, the PLB_PATH runtime buffer is cleared.
bufSize: This value identifies how many bytes of data are provided in the input buffer and is to be stored for the PLB_PATH keyword. If the bufSize value is zero, the PLB_PATH runtime buffer is cleared.

Control	Return	Key Value	Config Value	Buffer	BuffLen
GET_PLB_AAMUPPER	0/256/-nn	Req	NA	bufPtr	bufSize

Where:

0/256/-nn: The returned value can be zero, 256, or a negative value. If the returned value is zero, the PLB_AAMUPPER keyword buffer does not have any data. If the returned value is 256, the 256 bytes of data have been returned in the bufPtr buffer. If a negative value is returned, an error has occurred.
bufPtr: The Buffer input parameter is a pointer to a buffer that is to receive the PLB_AAMUPPER data.
maxSize: The maximum number of bytes that can be stored into the bufPtr buffer.

Control	Return	Key Value	Config Value	Buffer	BuffLen
SET_PLB_AAMUPPER	0/-nn	Req	NA	bufPtr	bufSize

Where:

0/-nn: The returned value can be either a zero that indicates that the PLB_AAMUPPER was successfully set or it is a negative value that indicates that an error has occurred.
bufPtr: This is a u8 pointer to a buffer that contains the input data to be stored for the PLB_AAMUPPER keyword. The bufPtr must contain 256 bytes of data used to perform uppercase translations. See the PLB_AAMUPPER keyword description for more details. If the bufPtr pointer is NULL, the PLB_AAMUPPER runtime buffer is cleared.
bufSize: This value identifies how many bytes of data are provided in the input buffer and is to be stored for the PLB_AAMUPPER keyword. This value can be either zero or a value of 256. If a bufSize of zero is specified, the PLB_AAMUPPER runtime buffer is cleared.

The following error values have been added to support the SA_Config function.

Value	Meaning
-102	Invalid SET_PLB_EOR ConfigValue
-103	Invalid SA_CONFIG KeyValue
-104	Invalid BufLen for SA_CONFIG
-105	Unable to allocate memory for SA_CONFIG
-106	Error setting SET_OPENUSEIP, SET_PREPUSEIP, or SET_DMALTIP
-107	Invalid ConfigValue for SET_PLB_COPYFILEBUFFSZ