DATASAVE - save data statement


[name] DATASAVE [AREA={s|Ns|N±value|U±value|1}]
                [,CONVERT={YES|NO}]
                [,COUNT=value]
                [,FUNCTION={BITAND}
                           {BITOR}
                           {BITXOR}
                           {B2X}
                           {CENTER}
                           {COPIES}
                           {DELWORD}
                           {OVERLAY}
                           {REVERSE}
                           {SPACE}
                           {STRIP}
                           {STRIPL}
                           {STRIPT}
                           {SUBWORD}
                           {X2B}
                           {X2C}
                           {INSERT}
                           {DELETE}
                           {LEFT}
                           {RIGHT}
                           {DBCSADD}
                           {DBCSADJ}
                           {DBCSDEL}
                           {DBCS2SB}
                           {SB2DBCS}
                           {SB2MDBCS}
                           {TRANSLATE}]
                [,INSERT=(data)]
                [,LENG={value|100}]
                [,LOC={B±value}
                      {C±value}
                      {D+value}
                      {TH+value}
                      {RH+value}
                      {RU+value}
                      {(row,col)}
                      {*}]
                [,PAD={char|blank}]
                [,PLENG=value]
                [,POS=value]
                [,TABLEI=data]
                [,TABLEO=data]
                [,TEXT=([data])]
                [,TEXT2=([data])]

Function

The DATASAVE statement saves device buffer data or explicitly specified data into a save area or user area. You can also use the DATASAVE statement to clear a specified save area or user area.

Where

name

Function: Specifies a name to be used when branching during message generation.

Format: From one to eight alphanumeric characters.

Default: None. This field is optional.

AREA={s|Ns|N±value|U±value|1}

Function: Specifies whether one of the save areas or user areas is to be used to save the data.

Format: For the AREA operand, you can enter one of the following options. The value for value can be any integer from 0 to 32766 or a counter specification whose value is within this range. Zero is the offset to the first byte of the field for positive offsets (+value) and the offset to the last byte of the field for negative offsets (-value).

s: Specifies a device save area to be used to save the data, where s is an integer from 1 to 4095.
Ns: Specifies a network save area to be used to save the data, where s is an integer from 1 to 4095.
N±value: Specifies a network user area to be used to save the data, where +value is the offset from the start of the user area and -value is the offset back from the end of the user area.
U±value: Specifies a device user area to be used to save the data, where +value is the offset from the start of the user area and -value is the offset back from the end of the user area.
Note: If value specifies an offset that is outside the user area, no data is saved and an informational message is written to the log data set.

Default: 1, indicating device save area number 1.

CONVERT={YES|NO}

Function: Specifies that the data to be saved will be converted from a hexadecimal format to a printable format before being placed in the save area or user area.

Format: For the CONVERT operand, you can code one of the following values:

YES: Specifies that each byte of data to be saved will be converted into two bytes, which are the EBCDIC representations of each of the two hexadecimal digits in the byte being saved. For example, the hexadecimal character X'C1' would be converted to the hexadecimal characters X'C3F1'.
Note: If CONVERT=YES is coded, the amount of space required in the save area or user area will be twice the value specified by the LENG operand.
NO: Specifies that the data to be saved will not be converted.

Default: NO

COUNT=value

Function: When FUNCTION=COPIES is coded, value specifies the number of copies to create.

Note: This operand is only valid when the TEXT operand is coded and when FUNCTION=COPIES is coded.

Format: An integer from 1 to 32767 or a counter specification whose value is within this range.

Default: None. This operand is required when FUNCTION=COPIES.

FUNCTION={BITAND}

{BITOR}

{BITXOR}

{B2X}

{CENTER}

{COPIES}

{DELWORD}

{OVERLAY}

{REVERSE}

{SPACE}

{STRIP}

{STRIPL}

{STRIPT}

{SUBWORD}

{X2B}

{X2C}

{INSERT}

{DELETE}

{LEFT}

{RIGHT}

{DBCSADD}

{DBCSADJ}

{DBCSDEL}

{DBCS2SB}

{SB2DBCS}

{SB2MDBCS}

{TRANSLATE}

Function: Specifies that a string manipulation function be performed on the TEXT operand.

Note: This operand is only valid when the TEXT operand is coded.

Format: You can code one of the following values for the FUNCTION operand:

BITAND

Specifies that the data coded for the TEXT and TEXT2 operands will be logically AND'ed together, bit by bit. If the PAD operand is specified, the shorter text data of TEXT and TEXT2 will be extended with the PAD character on the right before carrying out the logical operation.

BITOR

Specifies that the data coded for the TEXT and TEXT2 operands will be logically inclusive-OR'ed together, bit by bit. If the PAD operand is specified, the shorter text data of TEXT and TEXT2 will be extended with the PAD character on the right before carrying out the logical operation.

BITXOR

Specifies that the data coded for the TEXT and TEXT2 operands will be logically eXclusive-OR'ed together, bit by bit. If the PAD operand is specified, the shorter text data of TEXT and TEXT2 will be extended with the PAD character on the right before carrying out the logical operation.

B2X

Specifies that the data coded for the TEXT operand will be converted to hexadecimal.

CENTER

Specifies that the data coded for the TEXT operand will be centered with the PAD character around both ends until a length of PLENG is reached.

COPIES

Specifies that the data coded for the TEXT operand will be copied and concatenated by the number specified on the COUNT operand.

DELWORD

Specifies that the data coded for the TEXT operand will be deleted starting at the word corresponding to the value coded on the POS operand for a length of PLENG words.

OVERLAY

Specifies that the data coded for the INSERT operand is to be overlaid on the data specified by the TEXT operand. If the PLENG operand is also coded, the data specified by the INSERT operand is padded or truncated to that length before it is overlaid on the TEXT data. If the POS operand is also specified, the INSERT data is overlaid starting at that position in the TEXT data. If the PAD operand is specified, the specified PAD character is used, if necessary, to extend the TEXT or INSERT data to meet the POS or PLENG specifications respectively.

REVERSE

Specifies that the data coded for the TEXT operand will be reversed.

SPACE iref refid=space02.

Specifies that the data coded for the TEXT operand will have a space of length PLENG between each word. If the PAD operand is coded, the PAD value is used instead of a space.

STRIP

Specifies that the data coded for the TEXT operand will have both leading and trailing blanks removed. If the PAD operand is coded, the PAD value will be used as the character to remove instead of blanks.

STRIPL

Specifies that the data coded for the TEXT operand will have leading blanks removed. If the PAD operand is coded, the PAD value will be used as the character to remove instead of blanks.

STRIPT

Specifies that the data coded for the TEXT operand will have trailing blanks removed. If the PAD operand is coded, the PAD value will be used as the character to remove instead of blanks.

SUBWORD

Specifies that a substring of the data coded for the TEXT operand will start at the nth word coded by the n value of the POS operand and up to the PLENG value coded for the number of words. If the PLENG value is not coded, the default will be the number of remaining words in the data coded for the TEXT operand.

X2B

Specifies that the data coded for the TEXT operand will be converted to binary. Each hexadecimal character is converted to a string of four binary digits. Blanks are ignored.

X2C

Specifies that the data coded for the TEXT operand will be converted to character. A leading 0 will be added if necessary to make an even number of hexadecimal digits.

INSERT

Specifies that the data coded for the INSERT operand is to be inserted into the data specified by the TEXT operand. If the PLENG operand is also coded, the data specified by the INSERT operand is padded or truncated to that length before it is inserted. If the POS operand is also specified, the INSERT data is inserted after that position in the TEXT data. If the PAD operand is specified, the INSERT data is padded with the specified pad character.

DELETE

Specifies that a substring of the data coded for the TEXT operand is to be deleted, starting at the position specified by the POS operand. If the PLENG operand is also specified, its value is the number of characters deleted.

LEFT

Specifies that the data coded for the TEXT operand is to be padded or truncated on the right to the length specified by the PLENG operand. If the PAD operand is specified, the data is padded with the specified pad character.

RIGHT

Specifies that the data coded for the TEXT operand is to be padded or truncated on the left to the length specified by the PLENG operand. If the PAD operand is specified, the data is padded with the specified pad character.

DBCSADD

Adds SO/SI characters to the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

DBCSADJ

Deletes SI/SO character pairs from the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

DBCSDEL

Deletes SO/SI characters from the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

DBCS2SB

Converts ward 42 (EBCDIC) DBCS data to SBCS data in the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

SB2DBCS

Converts SBCS data to ward 42 (EBCDIC) DBCS data in the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

SB2MDBCS

Converts SBCS data to ward 42 (EBCDIC) DBCS data with SO/SI characters wrapped around it in the data coded for the TEXT operand and saves the result in the user area or save area specified by the AREA operand.

TRANSLATE

Specifies that the data coded for the TEXT operand is to be translated using the TABLEI, TABLEO, and PAD operand values. The data specified by TABLEI is searched for each character of the TEXT string. If found, the corresponding character in the data specified by the TABLEO operand replaces the TEXT character in the result. If the TEXT character is not found in the TABLEI data, it is left unchanged in the result. If a character occurs more than once in the TABLEI data, the first occurrence is the one used. If the TABLEO data is shorter than the TABLEI data, the TABLEO data is padded with the character specified by the PAD operand.

If TABLEO, TABLEI, and PAD are all omitted, lower case characters in the TEXT data are translated to upper case and all other characters are unchanged.

For individual defaults for TABLEO, TABLEI, and PAD, see those operand descriptions.

Default: None. This operand is optional.

INSERT=(data)

Function: Specifies the string data to be inserted into the data coded in the TEXT operand.

Note: This operand is only valid when the TEXT operand is coded and when FUNCTION=INSERT or FUNCTION=OVERLAY is coded.

Format: You can code any amount of data for this operand. If the resulting string is longer than the space available in the save area, the data is truncated and a message is written to the log data set.

The data is enclosed by the text delimiting character specified on the MSGTXT statement. (The defaults are left and right parentheses.) You can also continue the data.

You can use the data field options (see Data field options). To enter hexadecimal data, enclose the digits within single quotes. To enter a single quote, a special control character (CONCHAR), or a text delimiter (TXTDLM) as data, enter two of the characters. If you enter two text delimiting characters, they must be on the same statement; you cannot continue the statement between the characters.

Default: None.

LENG={value|100}

Function: Specifies, in bytes, the amount of data to be saved for later recall. If the specified length is greater than the space available in the save area or user area, the available length is used, and an informational message is written to the log data set. If the LENG operand value is greater than the length of the data in the device buffer, only the available data is saved.

Note: This operand is not valid if the TEXT operand is coded.

Format: value can be an integer from 1 to 32767 or a counter specification whose value is within this range.

Default: 100

LOC={B±value|C±value|D+value|TH+value|RH+value|RU+value|(row,col)|*}

Function: Specifies the location of the data to be saved.

If the DATASAVE statement is encountered as a result of an IF statement execute function (that is, THEN=Ename-label) with WHEN=IN coded, then data is saved from the device input buffer. Otherwise, data is saved from the device output buffer. For display devices, the output buffer is the screen image if B±, C±, or (row,col) is specified.

Note: This operand is not valid if the TEXT operand is coded.

Format: For the LOC operand, you can code one of the following options. value can be an integer from 0 to 32766 or a counter specification whose value is within this range. Zero is the offset to the first byte of the field for positive offsets (+value) and the offset to the last byte of the field for negative offsets (-value).

B±value: +value specifies that the data to be saved is at an offset from the start of the device buffer, excluding any headers. For display devices, -value indicates an offset back from the end of the screen image buffer. For non-display devices, -value indicates an offset back from the end of the data in the device buffer.
C±value: +value specifies an offset from the current cursor position. -value specifies an offset back from the cursor. You should use this value only with display devices.
D+value: +value specifies an offset from the start of the data stream.
TH+value: +value specifies an offset from the start of the transmission header.
RH+value: +value specifies an offset from the start of the request header.
RU+value: +value specifies an offset from the start of the request unit.
(row,col): Indicates that the test is to be made at the specified row and column of the screen image of a display device, where row and col may be an integer from 1 to 255 or a counter specification whose value is within this range. You should use this value only with display devices.
*: Specifies that data is to be saved from the input area location that was coded on the last logic test that was executed and had its THEN action taken. This option is valid only when the DATASAVE statement is encountered as a result of a logic test execute function, (for example, THEN=Ename-label). The data to be saved begins with the first character of the data string that satisfied the logic test. If the last logic test executed did not specify a device buffer location, or its THEN action was not an execute function, no data is saved and an informational message is written to the log data set.

Default: B+0

PAD={char|blank}

Function: Specifies the character to be used as padding when BITAND, BITOR, BITXOR, CENTER, OVERLAY, SPACE, STRIP, STRIPL, STRIPT, INSERT, LEFT, RIGHT, or TRANSLATE is specified for the FUNCTION operand.

Note: This operand is only valid when the TEXT operand is coded along with the specified functions.

Format: char is a 1-character string constant or a 2-character hexadecimal constant. When you use a special character (such as a quote or parenthesis) as padding, do not double it.

Default: When FUNCTION=BITAND is coded, the default is X'FF'. When BITOR or BITXOR is coded for the FUNCTION operand, the default is X'00'. Otherwise, the default is blank (X'40').

PLENG=value

Function: When INSERT or OVERLAY is coded for the FUNCTION operand, value specifies the number of characters to which the data specified by the INSERT operand is truncated or padded when data is inserted into, or overlaid on, the data specified by the TEXT operand. When FUNCTION=DELETE is coded, value specifies the number of characters to be deleted. When FUNCTION=SPACE is coded, value specifies the number of blanks or characters specified by the PAD operand, to place between the words. If value is 0, all blanks are removed. Leading and trailing blanks are always removed. When CENTER, LEFT or RIGHT is coded for the FUNCTION operand, value specifies the number of characters to which the data coded for the TEXT operand is truncated or padded. When DELWORD or SUBWORD is coded for the FUNCTION operand, value specifies the number of words to delete or return.

Note: This operand is only valid when the TEXT and FUNCTION operands are coded.

Format: An integer from 0 to 32767 or a counter specification whose value is within the range.

Default: When INSERT or OVERLAY is coded for the FUNCTION operand, the default is the length of the data specified by the INSERT operand. When FUNCTION=DELETE is coded, the default is the length of the TEXT data after the position specified by the POS operand. When FUNCTION=SPACE is coded, the default is 1. When CENTER, LEFT or RIGHT is coded for the FUNCTION operand, there is no default, and a value is required. When DELWORD or SUBWORD is coded for the FUNCTION operand, the default is the number of words left in the TEXT data after the word in the position specified by the POS operand.

POS=value

Function: When FUNCTION=INSERT is coded, value specifies the position in the TEXT data after which the data coded for the INSERT operand is inserted. When FUNCTION=OVERLAY is coded, value specifies the first position in the TEXT data to be overlaid with the data coded for the INSERT operand. When FUNCTION=DELETE is coded, value specifies the first position in the TEXT data to be deleted. When DELWORD or SUBWORD is coded for the FUNCTION operand, value specifies the word position in the TEXT data.

Note: This operand is only valid when the TEXT operand is coded and when DELETE, DELWORD, INSERT, OVERLAY or SUBWORD is coded on the FUNCTION operand.

Format: When FUNCTION=INSERT is coded, value can be an integer from 0 to 32766 or a counter specification whose value is within that range. If value is greater than the length of the data specified in the TEXT operand, pad characters are inserted after the TEXT data, with the INSERT data following. If value is zero, the data coded in the INSERT operand is inserted before the beginning of the data coded in the TEXT operand.

When FUNCTION=OVERLAY is coded, value can be an integer from 1 to 32767 or a counter specification whose value is within that range. If value is greater than the length of the data specified in the TEXT operand, pad characters are added to the TEXT data.

When DELETE, DELWORD or SUBWORD is coded on the FUNCTION operand, value can be an integer from 1 to 32767 or a counter specification whose value is within that range.

Default: When FUNCTION=INSERT is coded, the default is 0. When FUNCTION=OVERLAY is coded, the default is 1. When DELETE, DELWORD or SUBWORD is coded for the FUNCTION operand, there is no default and a value must be specified.

TABLEI=(data)

Function: Specifies the input table to be used with the translation of the data coded in the TEXT operand.

Note: This operand is only valid when the TEXT operand is coded and when FUNCTION=TRANSLATE is coded.

Format: You can code any amount of data for this operand, but you would not normally code more than 256 characters. See the description of the TRANSLATE function under the FUNCTION operand for details of how this data is used.

The data is enclosed by the text delimiting character specified on the MSGTXT statement. (The defaults are left and right parentheses.) You can also continue the data.

Default: If TABLEO or PAD is coded, the default for TABLEI is the 256 byte string of hexadecimal codes 00,01,02,..., FF. Otherwise, no default.

TABLEO=(data)

Function: Specifies the output table to be used with the translation of the data coded in the TEXT operand.

Note: This operand is only valid when the TEXT operand is coded and when FUNCTION=TRANSLATE is coded.

The data is enclosed by the text delimiting character specified on the MSGTXT statement. (The defaults are left and right parentheses.) You can also continue the data.

Default: If TABLEI or PAD is coded, the default for TABLEO is a string of repeated PAD characters equal in length to the data specified or defaulted for TABLEI. Otherwise, no default.

TEXT=([data])

Function: Specifies the text data to be saved in the save area or user area based on the function specified for the FUNCTION operand.

Note: If this operand is coded, the LENG and LOC operands are not valid.

Format: You can code any amount of data for this operand. If the data is longer than the space available in the save area or user area, it is truncated, and an informational message is written to the log data set.

The data is enclosed by the text delimiting characters specified on the MSGTXT statement. (The default is left and right parentheses.) You can also continue the data.

You can use the data field options (see Data field options). Enter hexadecimal data by enclosing the digits within single quotes. To enter a single quote, a special control character (CONCHAR), or a text delimiting character (TXTDLM) as data, enter two of the characters. If two text delimiting characters are entered, they must be on the same statement (no continuation between the characters).

If the TEXT operand specifies only two text delimiting characters with no intervening data (for example, TEXT=(),), a clear function is executed. Specifying TEXT=() also frees a dynamically allocated save area. If the AREA operand specifies a save area number, the length of data saved in that save area is set to zero. If the AREA operand specifies an offset into a user area, the user area is usually cleared to binary zeros from the specified offset to the end. This will not be the case if the FUNCTION operand or CONVERT=YES has also been specified. In those cases, the user area is unchanged.

Default: None. This operand is optional.

TEXT2=([data])

Function: Specifies the text data to be used when BITAND, BITOR or BITXOR is coded for the FUNCTION operand.

Note: If this operand is coded, the LENG and LOC operands are not valid.

Format: See the TEXT description above.

Default: None. This operand is optional.