|
|
|
|
The Copy Field to String function copies all the characters in a specified field in the current presentation space to a data string in your application program. Copied characters are translated from EBCDIC (used in the host presentation space) to ASCII before they are stored in the data string.
Your application program must be connected to a valid presentation space before issuing this function. Use Connect Presentation Space to connect to a presentation space.
Your application program must pass the following parameters to this function:
An empty data string to hold the information copied from the field. This string must be at least the length specified in the data_length parameter.
Number of bytes you want to copy from the specified field. If the option is set in Set Session Parameters, this must be twice the number of character positions in the field, because each character copied will be followed by its EAB.
Position of the field you want to copy in the presentation space. The value you supply here can be any position within the target field (including the position of the attribute byte), but the copy will always begin at the first position of the field.
The range for this number depends on the type of display you are using. Presentation Space Sizes, shows the PS positions for each of the display models.
This function returns the following parameters to your application program:
34
Information copied from the beginning of the field identified by ps_position.
The number of characters in the returned data string.
The valid return codes are:
Function was successful; field was copied to your application program.
Application program is not connected to a valid presentation space.
A supplied parameter was not valid.
Field in the presentation space was not the same length as the data_length parameter supplied by your application program (either longer or shorter). Some data may have been truncated.
Your application program specified a presentation space position that is not valid.
System error occurred.
String or field was not found, or host presentation space was unformatted.
This function is affected by the following options of the Set Session Parameters function:
Copies each character from the presentation space followed by its extended attribute byte.
Does not copy attribute bytes.
If the option is set, causes the copied extended attribute bytes to be translated into CGA format. If the option is not set, is ignored.
If the option is set, causes extended attribute bytes to be copied without translation. If the option is not set, is ignored.
For more information, see Set Session Parameters.
Usage and restrictions are:
This function copies the field beginning with the byte immediately following the attribute information for the field.
This function can copy from protected and unprotected fields.
This function stops copying when it encounters one of the following conditions:
End of the field is encountered
Number of characters specified in data_length are copied
Use the Find Field Position function to find the position of the field in the presentation space you want to copy.
Use the Find Field Length function to find the length of the field you want to copy.
If the specified field extends beyond the end of the presentation space, the copy wraps to the start of the presentation space.
This function does not add a null character to the end of the copied string. If you want to use the copied string directly in your program, use a string that is at least one byte longer than the data to be copied, and use memset to preset the whole string to nulls before passing it as a parameter to this function; this will ensure you have a correctly null-terminated string. However, the data_length parameter should still contain the number of bytes to be copied, not the length of the supplied string.
|
|
|
 |
|