|
|
|
|
This chapter contains a description of each of the Common Service Verbs. The following information is provided for each verb:
Definition of the verb.
Structure defining the verb control block (VCB) used by the verb. The structure is declared in the CSV header file.
Parameters (VCB fields) supplied for and returned by the verb. For each parameter, the following information is provided:
Description
Possible values
Additional information
Additional information describing the use of the verb.
Most parameters supplied with and returned by Common Service Verbs are
hexadecimal values. To simplify coding, these values are represented by meaningful
symbolic constants defined in the header file values_c.h,
which is included by the CSV header file acssvcc.h.
For example, the opcode (operation code) parameter
for the CONVERT verb is the hexadecimal value represented by the symbolic
constant
It is important that you use the symbolic constant and not the hexadecimal value when setting values for supplied parameters, or when testing values of returned parameters. This is because different systems store these values differently in memory, so the value shown may not be in the format recognized by your system.
If you are writing applications for use in other environments as well as SNAP-IX, see Writing Portable Applications.
The CSV VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The CONVERT verb translates an ASCII character string to EBCDIC or an EBCDIC character string to ASCII.
The string to be converted is called the source string. The converted string is called the target string.
typedef struct convert
{
AP_UINT16 opcode; /* Verb identifying operation code. */
unsigned char opext; /* Verb extension code - reserved. */
unsigned char reserv2; /* Reserved. */
AP_UINT16 primary_rc; /* Primary return code from verb. */
AP_UINT32 secondary_rc; /* Secondary (qualifying) return code. */
unsigned char direction; /* Direction of conversion - ASCII to */
/* EBCDIC or vice-versa. */
unsigned char char_set; /* Character set to use for the */
/* conversion A, AE, or user-defined G. */
AP_UINT16 len; /* Length of string to be converted. */
unsigned char *source; /* Pointer to string to be converted. */
unsigned char *target; /* Address to put converted string at. */
};
typedef struct convert
{
unsigned short opcode; /* Verb identifying operation code. */
unsigned char opext; /* Verb extension code - reserved. */
unsigned char reserv2; /* Reserved. */
unsigned short primary_rc; /* Primary return code from verb. */
unsigned long secondary_rc; /* Secondary (qualifying) return code. */
unsigned char direction; /* Direction of conversion - ASCII to */
/* EBCDIC or vice-versa. */
unsigned char char_set; /* Character set to use for the */
/* conversion A, AE, or user-defined G. */
unsigned short len; /* Length of string to be converted. */
unsigned char *source; /* Pointer to string to be converted. */
unsigned char *target; /* Address to put converted string at. */
}; 
The program using this verb supplies the following parameters:
Possible values are:
Specifies which character set to use in converting the source string. Possible values are:
The type-A character set consists of the following:
Uppercase letters
Numerals 0-9
Special characters $, #, @, and space
This character set is supported by a system-supplied type-A conversion table.
The first character of the source string must be an uppercase letter or the special character $, #, or @. Spaces are allowed only in trailing positions. Lowercase letters can be supplied in positions other than the first character, but will be translated to uppercase.
The type-AE character set consists of the following:
Uppercase letters
Lowercase letters
Numerals 0-9
Special characters $, #, @, and space
This character set is supported by a system-supplied type-AE conversion table.
The first character of the source string can be any character in the character set. Spaces are allowed only in trailing positions, unless the string consists entirely of spaces. No case conversion is performed.
The type-G character set is defined by a user-written conversion table. This table is described in detail under Creating a Type-G Conversion Table.
The file containing the table must be specified by the environment variable
For Win32 clients, the file containing the table must be specified by the CSVTBLG value Registry Key as follows:
\\HKEY_LOCAL_MACHINE\SOFTWARE\SNA Client\SxClient\Parameters\CSV_data
The CSVTBLG parameter is described in the SNAP-IX Administration Guide. Set this parameter to the full path name of the file. (If the file is not found, the system returns the SV_TABLE_ERROR return code.)
The number of characters to be converted.
Address of buffer containing character string to be converted.
Address of buffer to contain the converted character string.
This buffer can overlap or coincide with the buffer pointed to by the source parameter. In this case, the converted data string overwrites the source data string.
After the verb executes, SNAP-IX returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful.
If the verb executes successfully, SNAP-IX returns the following parameter:
SV_OK
When a verb does not execute successfully, SNAP-IX returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:
SV_PARAMETER_CHECK
Possible values are:
One or more characters in the source string were not found in the conversion table, or embedded spaces were found in a type-A or type-AE string. These characters or spaces were converted to nulls (0x00). The verb still executed.
The char_set parameter contained a value that is not valid.
The supplied source or target string extended beyond the boundary of a data segment, or the target data segment was not a read/write segment.
The direction parameter contained a value that is not valid.
The first character of a type-A source string is not a valid value.
The file containing the user-written type-G conversion table was not defined correctly, could not be accessed, or was not in the correct format.
The file containing the table must be specified by the environment variable
For Win32 clients, the file containing the table must be specified by the CSVTBLG value Registry Key as follows:
\\HKEY_LOCAL_MACHINE\SOFTWARE\SNA Client\SxClient\Parameters\CSV_data
The CSVTBLG parameter is described in the SNAP-IX Administration Guide. Set this parameter to the full path name of the file.
Other conditions can result in the following primary return codes ( primary_rc).
The SNAP-IX software has not been started. Consult the System Administrator for corrective action.
The supplied VCB extended beyond the boundary of a data segment.
The opcode parameter did not match the operation code of any verb. No verb executed.
The operating system has encountered an error while processing the verb. The operating system return code is returned through the secondary_rc . If the problem persists, consult the System Administrator for corrective action.
For the meaning of the operating system return code, see the file /usr/include/errno.h.
For the meaning of the operating system return code, refer to your operating system documentation.
You can use the GET_CP_CONVERT_TABLE verb to build a type-G, user-written conversion table. The GET_CP_CONVERT_TABLE verb is described in detail later in this chapter.
The table must be an ASCII file 32 lines long. Each line must consist of 32 hexadecimal digits, representing 16 characters. The first 16 lines (256 characters) specify the EBCDIC characters to which ASCII characters are converted; the remaining 16 lines specify the ASCII characters to which EBCDIC characters are converted.
For SNAP-IX, the hexadecimal digits A-F can be either uppercase or lowercase. However, you may want to make these digits uppercase to ensure compatibility with the CSV implementation provided in the IBM OS/2 Extended Edition.
The file /opt/sna/samples/snatblg.dat delivered with SNAP-IX contains a sample type-G conversion table which converts the first 127 characters of an ASCII code page to EBCDIC. Here is a listing of that file:
00010203372D2E2F1605250B0C0D0E0F 101112133C3D322618193F27221D351F 405A7F7B5B6C507D4D5D5C4E6B604B61 F0F1F2F3F4F5F6F7F8F97A5E4C7E6E6F 7CC1C2C3C4C5C6C7C8C9D1D2D3D4D5D6 D7D8D9E2E3E4E5E6E7E8E9ADE0BD5F6D 79818283848586878889919293949596 979899A2A3A4A5A6A7A8A9C06AD0A107 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000000 000102030009007F0000000B0C0D0E0F 101112130000080018190000001D001F 00001C00000A171B0000000000050607 00001600001E0004000000001415001A 20000000000000000000002E3C282B00 2600000000000000000021242A293B5E 2D2F00000000000000007C2C255F3E3F 000000000000000000603A2340273D22 00616263646566676869000000000000 006A6B6C6D6E6F707172000000000000 007E737475767778797A0000005B0000 000000000000000000000000005D0000 7B414243444546474849000000000000 7D4A4B4C4D4E4F505152000000000000 5C00535455565758595A000000000000 30313233343536373839000000000000
|
|
|
 |
|