Convert SNA to Character (CVTSC)

Operand 2: Character(14) variable scalar.

Operand 3: Character scalar.

Operand 4-6:

• Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction number.

• Indicator Form-Numeric variable scalar or character variable scalar.

Built-in number for CVTSC is 134.
CVTSC (
       receiver          : address
       receiver_length   : unsigned binary(4)
       controls          : address
       source            : address
       source_length     : unsigned binary(4)
       return_code       : address of signed binary(4)
)

Description

This instruction converts a string value from SNA (systems network architecture) format to character. The operation converts the source (operand 3) from SNA format to character under control of the controls (operand 2) and places the result into the receiver (operand 1).

The source and receiver operands must both be character strings. The source operand may not be specified as an immediate operand.

The controls operand must be a character scalar that specifies additional information to be used to control the conversion operation. It must be at least 14 bytes in length and have the following format:

Upon input to the instruction, the source offset and receiver offset fields specify the offsets where bytes of the source and receiver operands are to be processed. If an offset is equal to or greater than the length specified for the operand it corresponds to (it identifies a byte beyond the end of the operand), a template value invalid  (hex 3801) exception is signaled. As output from the instruction, the source offset and receiver offset are set to specify offsets that indicate how much of the operation is complete when the instruction ends.

The algorithm modifier specifies the optional functions to be performed. Any combination of functions not precluded by the bit definitions below is valid except that at least one of the functions must be specified. All algorithm modifier bits cannot be zero. Specification of an invalid algorithm modifier value results in a template value invalid  (hex 3801) exception. The meaning of the bits in the algorithm modifier is the following:

The receiver record length value specifies the record length to be used to convert source records into the receiver operand. This length applies only to the data portion of the receiver record and does not include the optional record separator. Specification of a receiver record length of zero results in a template value invalid  (hex 3801) exception. The receiver record length value is ignored if no record separator processing is requested in the algorithm modifier.

The record separator value specifies the character that is to precede the converted form of each record in the receiver. The record separator character specified in the controls operand is used only for the case where the move record separator from controls to receiver function is specified in the algorithm modifier or where a missing record separator in the source is detected.

The prime compression value specifies the character to be used as the prime compression character when performing decompression of the SNA format source data to character. It may have any value. The prime compression value is ignored if the perform decompression function is not specified in the algorithm modifier.

The unconverted receiver record bytes value specifies the number of bytes remaining in the current receiver record that are yet to be set with converted bytes from the source.

When record separator processing is specified in the algorithm modifier, this value is both input to and output from the instruction. On input, a value of hex 00 means it is the start of processing for a new record, and the initial conversion step is yet to be performed. This indicates that for the case where a function for putting record separators into the receiver is specified in the algorithm modifier, a record separator character has yet to be placed in the receiver. On input, a nonzero value less than or equal to the receiver record length specifies the number of bytes remaining in the current receiver record that are yet to be set with converted bytes from the source. This value is assumed to be the valid count of unconverted receiver record bytes relative to the current byte to be processed in the receiver as located by the receiver offset field. As such, it is used to determine the location of the next record boundary in the receiver operand. This value must be less than or equal to the receiver record length value; otherwise, a template value invalid  (hex 3801) exception is signaled. On output, this field is set with a value as defined above which describes the number of bytes of the current receiver record not yet containing converted data.

When record separator processing is not specified in the algorithm modifier, this value is ignored.

The conversion status field specifies status information for the operation to be performed. The meaning of the bits in the conversion status is the following:

If the conversion status indicates transparency string active, but the algorithm modifier does not specify perform data transparency conversion, a template value invalid  (hex 3801) exception is signaled.

The unconverted transparency string bytes field specifies the number of bytes remaining to be converted for a partially processed transparency string in the source.

When perform data transparency conversion is specified in the algorithm modifier, the unconverted transparency string bytes field can be both input to and output from the instruction.

On input, when the no transparency string active status is specified in the conversion status, this value is ignored.

On input, when transparency string active status is specified in the conversion status, this value contains a count for the remaining bytes to be converted for a transparency string in the source. A value of hex 00 means the count field for a transparency string is the first byte of data to be processed from the source operand. A value of hex 01 through hex FF specifies the count of the remaining bytes to be converted for a transparency string. This value is assumed to be the valid count of unconverted transparency string bytes relative to the current byte to be processed in the source as located by the source offset field.

On output, this value is set if necessary along with the transparency string active status to describe a partially converted transparency string. A value of hex 00 will be set if the count field is the next byte to be processed for a transparency string. A value of hex 01 through hex FF specifying the number of remaining bytes to be converted for a transparency string, will be set if the count field has already been processed.

When do not perform data transparency conversion is specified in the algorithm modifier, the unconverted transparency string bytes value is ignored.

The offset into template to translate table value specifies the offset from the beginning of the template to the record separator translate table. This value is ignored unless the translate record separators from source to receiver function is specified in the algorithm modifier.

The record separator translate table value specifies the translate table to be used in translating record separators specified in the source to the record separator value to be placed into the receiver. It is assumed to be 64 bytes in length, providing for translation of record separator values from hex 00 to hex 3F. This translate table is used only when the translate record separators from source to receiver function is specified in the algorithm modifier. See the record separator conversion function under the conversion process described below for more detail on the usage of the translate table.

Only the first 14 bytes of the controls operand base template and the optional 64-byte extension area specified for the record separator translate table are used. Any excess bytes are ignored.

The description of the conversion process is presented as a series of separately performed steps, which may be selected in allowable combinations to accomplish the conversion function. It is presented this way to allow for describing these functions separately. However, in the actual execution of the instruction, these functions may be performed in conjunction with one another or separately, depending upon which technique is determined to provide the best implementation.

The operation is performed either on a record-by-record basis, record processing, or on a nonrecord basis, string processing. This is determined by the functions selected in the algorithm modifier. Specifying the record separators in source, perform blank padding or move record separator from controls to receiver indicates record processing is to be performed. If neither of these functions is specified, in which case decompression must be specified, it indicates that string processing is to be performed.

The operation begins by accessing the bytes of the source operand at the location specified by the source offset.

When record processing is specified, the source offset may locate a point at which processing of a partially converted record is to be resumed or processing for a full record is to be started. The unconverted receiver record bytes field indicates whether conversion processing is to be started with a partial or a full record. Additionally, the transparency string active indicator in the conversion status field indicates whether conversion of a transparency string is active for the case of resumption of processing for a partially converted record. The conversion process is started by completing the conversion of a partial source record if necessary before processing the first full source record.

When string processing is specified, the source offset is assumed to locate the start of a compression entry.

When during the conversion process the end of the receiver operand is encountered, the instruction ends with a resultant condition or receiver overrun.

When record processing is specified in the algorithm modifier, this check is performed at the start of conversion for each record. A source exhausted condition would be detected before a receiver overrun condition if there is no source data to convert. If the receiver operand does not have room for a full record, the receiver overrun condition is recognized. The instruction is terminated with status in the controls operand describing the last completely converted record. For receiver overrun, partial conversion of a source record is not performed.

When string processing is specified in the algorithm modifier, then decompression must be specified and the decompression function described below defines the detection of receiver overrun.

When during the conversion process the end of the source operand is encountered, the instruction ends with a resultant condition of source exhausted. See the description of this condition in the conversion process described below to determine the status of the controls operand values and the converted bytes in the receiver for each case.

When string processing is specified, the bytes accessed from the source are converted on a string basis into the receiver operand at the location specified by the receiver offset. In this case, the decompression function must be specified and the conversion process is accomplished with just the decompression function defined below.

When record processing is specified, the bytes accessed from the source are converted one record at a time into the receiver operand at the location specified by the receiver offset performing the functions specified in the algorithm modifier in the sequence defined by the following algorithm.

Record separator conversion is performed as requested in the algorithm modifier during the initial record separator processing performed as each record is being converted. This provides for controlling the setting of the record separator value in the receiver.

When the record separators in source option is specified, the following algorithm is used to locate them. A record separator is recognized in the source when a character value less than hex 40 is encountered. When do not perform decompression is specified, a source character value of hex 00 is recognized as a null value rather than as a record separator. In this case, the processing of the current record continues with the next source byte and the receiver is not updated. When perform data transparency conversion is specified, a character value of hex 35 is recognized as the start of a transparency string rather than as a record separator.

If the do not put record separators into the receiver function is specified, the record separator, if any, from the source record being processed is removed from the converted form of the source record and will not be placed in the receiver.

If the move record separators from the source to the receiver function is specified, the record separator from the source record being processed is left as is in the converted form of the source record and will be placed in the receiver.

If the translate record separators from the source to the receiver function is specified, the record separator from the source record being processed is translated using the specified translate table, replaced with its translated value in the converted form of the source record, and placed in the receiver. The translation is performed as in the translate instruction (XLATE) with the record separator value serving as the source byte to be translated. It is used as an index into the specified translate table to select the byte in the translate table that contains the value to which the record separator is to be set. If the selected translate table byte is equal to hex FF, it is recognized as an escape code. The instruction ends with a resultant condition of escape code encountered, and the controls operand is set to describe the conversion status as of the processing completed just prior to the conversion step for the record separator. If the selected translate table byte is not equal to hex FF, the record separator in the converted form of the record is set to its value.

If the move record separator from controls to receiver function is specified, the controls record separator value is used in the converted form of the source record and will be placed into the receiver.

When the record separators in source do blank padding function is requested, an assumed record separator will be used if a record separator is missing in the source data. In this case, the controls record separator character is used as the record separator to precede the converted record if record separators are to be placed in the receiver. The conversion process continues, bypassing the record separator conversion step that would normally be performed. The condition of a missing record separator is detected when during initial processing for a full record, the first byte of data is not a record separator character.

Decompression is performed if the function is specified in the algorithm modifier. This provides for converting strings of duplicate characters in compressed format in the source back to their full size in the receiver. Decompression of the source data is accomplished by concatenating together character strings described by the compression strings occurring in the source. The source offset value is assumed to locate the start of a compression string. Processing of a partial decompressed record is performed if necessary.

The character strings to be built into the receiver are described in the source by one or more compression strings. Compression strings are comprised of an SCB (string control byte) possibly followed by one or more bytes of data related to the character string to be built into the receiver.

The format of an SCB and the description of the data that may follow it is as follows:

Strings of nonduplicate characters described in the source record are formed into a decompressed character string for the length indicated by the SCB count value.

If the end of the source is encountered prior to the end of a compression string, a conversion  (hex 0C01) exception is signaled.

When record processing is specified, decompression is performed one record at a time. In this case, a conversion  (hex 0C01) exception is signaled if a compression string describes a character string that would span a record boundary in the receiver. If the source contains record separators, the case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion, as requested in the algorithm modifier, is performed as the initial step in the building of the decompressed record. A record separator to be placed into the receiver is in addition to the data to be converted into receiver for the length specified in the receiver record length field. The decompression of compression strings from the source continues until a record separator character for the next record is recognized when the source contains record separators, or until the decompressed data required to fill the receiver record has been processed or the end of the source is encountered whether record separators are in the source or not. Transparency strings encountered in the decompressed character string are not scanned for a record separator value. If the end of the source is encountered, the data decompressed to that point appended to the optional record separator for this record forms a partial decompressed record. Otherwise, the decompressed character strings appended to the optional record separator for this record form the decompressed record. The conversion process then continues for this record with the next specified function.

When string processing is specified, decompression is performed on a compression string basis with no record oriented processing implied. The conversion process for each compression string from the source is completed by placing the decompressed character string into the receiver. The conversion process continues decompressing compression strings from the source until the end of the source or the receiver is encountered. When the end of the source operand is encountered, the instruction ends with a resultant condition of source exhausted. When a character string cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. For either of the above ending conditions, the controls operand is updated to describe the status of the conversion operation as of the last completely converted compression entry. Partial conversion of a compression entry is not performed.

Data transparency conversion is performed if perform data transparency conversion is specified in the algorithm modifier. This provides for correctly identifying record separators in the source even if the data for a record contains values that could be interpreted as record separator values. Processing of active transparency strings is performed if necessary.

A nontransparent record is built by appending the nontransparent and transparent data converted from the record to the record separator for the record. The nontransparent record may be produced from either a partial record from the source or a full record from the source. This is accomplished by first accessing the record separator for a full record. The case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion as requested in the algorithm modifier is performed if it has not already been performed by a prior step; the rest of the source record is scanned for values of less than hex 40.

A value greater than or equal to hex 40 is considered nontransparent data and is concatenated onto the record being built as is.

A value equal to hex 35 identifies the start of a transparency string. A transparency string is comprised of 2 bytes of transparency control information followed by the data to be made transparent to scanning for record separators. The first byte has a fixed value of hex 35 and is referred to as the TRN (transparency) control character. The second byte is a 1-byte hexadecimal count, a value remaining from 1 to 255 decimal, of the number of bytes of data that follow and is referred to as the TRN count. A TRN count of zero is invalid and causes a conversion  (hex 0C01) exception. This contains the length of the transparent data and does not include the TRN control information length. The transparent data is concatenated to the nontransparent record being built and is not scanned for record separator characters.

A value equal to hex 00 is recognized as the record separator for the next record only when perform decompression is specified in the algorithm modifier. In this case, the nontransparent record is complete. When do not perform decompression is specified in the algorithm modifier, a value equal to hex 00 is ignored and is not included as part of the nontransparent data built for the current record.

A value less than hex 40 but not equal to hex 35 is considered to be the record separator for the next record, and the forming of the nontransparent record is complete.

The building of the nontransparent record is completed when the length of the data converted into the receiver equals the receiver record length if the record separator for the next record is not encountered prior to that point.

If the end of the source is encountered prior to completion of building the nontransparent record, the nontransparent record built up to this point is placed in the receiver and the instruction ends with a resultant condition of source exhausted. The controls operand is updated to describe the status for the partially converted record. This includes describing a partially converted transparency string, if necessary, by setting the active transparency string status and the unconverted transparency string bytes field.

If the building of the nontransparent record is completed prior to encountering the end of the source, the conversion process continues with the blank padding function described below.

Blank padding is performed if the function is specified in the algorithm modifier. This provides for expanding out to the size specified by the receiver record length the source records for which trailing blanks have been truncated. The padded record may be produced from either a partial record from the source or a full record from the source.

The record separator for this record is accessed. The case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion as requested in the algorithm modifier, is performed if it has not already been performed by a prior step.

The nontruncated data, if any, for the record is appended to the optional record separator for the record. The nontruncated data is determined by scanning the source record for the record separator for the next record. This scan is concluded after processing enough data to completely fill the receiver record or upon encountering the record separator for the next record. The data processed prior to concluding the scan is considered the nontruncated data for the record.

The blanks, if any, required to pad the record out to the nontruncated data for the record, concluding the forming of the padded record.

If the end of the source is encountered during the forming of the padded record, the data processed up to that point, appended to the optional record separator for the record, is placed into the receiver and the instruction ends with a resultant condition of source exhausted. The controls operand is updated to describe the status of the partially converted record.

If the forming of the padded record is concluded prior to encountering the end of the source, the conversion of the record is completed by placing the converted form of the record into the receiver.

At this point, either conversion of a source record has been completed or conversion has been interrupted due to detection of the source exhausted or receiver overrun condition. For record processing, if neither of the above conditions has been detected either during conversion of or at completion of conversion for the current record, the conversion process continues on the next source record with the decompression function described above.

At completion of the instruction, the receiver offset locates the byte following the last converted byte in the receiver. The value of the remaining bytes in the receiver after the last converted byte are unpredictable. The source offset locates the byte following the last source byte for which conversion was completed. When record processing is specified, the unconverted receiver record bytes field specifies the length of the receiver record bytes not yet containing converted data. When perform data transparency conversion is specified in the algorithm modifier, the conversion status indicates whether conversion of a transparency string was active and the unconverted transparency string bytes field specifies the length of the remaining bytes to be processed for an active transparency string.

This instruction does not provide support for compression entries in the source describing data that would span records in the receiver. SNA data from some systems may violate this restriction and as such be incompatible with the instruction. A provision can be made to avoid this incompatibility by performing the conversion of the SNA data through two invocations of this instruction. The first invocation would specify decompression with no record separator processing. The second invocation would specify record separator processing with no decompression. This technique provides for separating the decompression step from record separator processing; thus, the incompatibility is avoided.

This instruction can end with the escape code encountered condition. In this case, it is expected that the user of the instruction will want to do some special processing for the record separator causing the condition. In order to resume execution of the instruction, the user will have to set the appropriate value for the record separator into the receiver and update the controls operand source offset and receiver offset fields correctly to provide for restarting processing at the right points in the receiver and source operands.

For the special case of a tie between the source exhausted and receiver overrun conditions, the source exhausted condition is recognized first. That is, when source exhausted is the resultant condition, the receiver may also be full. In this case, the receiver offset may contain a value equal to the length specified for the receiver, which would cause an exception to be detected on the next invocation of the instruction. The processing performed for the source exhausted condition should provide for this case if the instruction is to be invoked multiple times with the same controls operand template. When the receiver overrun condition is the resultant condition, the source will always contain data that can be converted.

This instruction will, in certain cases, ignore what would normally have been interpreted as a record separator value of hex 00. This applies (hex 00 is ignored) for the special case when do not perform decompression and record separators in source are specified in the algorithm modifier. Note that this does not apply when perform decompression is specified, or when do not perform decompression and no record separators in source and move record separator from controls to receiver are specified in the algorithm modifier.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction.

• Any form of overlap between the operands on this instruction yields unpredictable results in the receiver operand.

Resultant Conditions

• Source exhausted-The end of the source operand is encountered and no more bytes from the source can be converted.

• Receiver overrun-An overrun condition in the receiver operand is detected before all of the bytes in the source operand have been processed.

• Escape code encountered-A record separator character is encountered in the source operand that is to be treated as an escape code.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

0C Computation

• 0C01 Conversion

10 Damage Encountered

• 1004 System Object Damage State
• 1044 Partial System Object Damage

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2201 Object Not Found
• 2202 Object Destroyed
• 2203 Object Suspended
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2C Program Execution

• 2C04 Branch Target Invalid

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3201 Scalar Type Invalid

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3801 Template Value Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed