| Op Code (Hex) | Extender | Operand 1 | Operand 2 | Operand 3 | Operand [4-5] |
|---|---|---|---|---|---|
| CVTCS 10CB |
| Receiver | Controls | Source |
|
|
| |||||
| CVTCSB 1CCB | Branch options | Receiver | Controls | Source | Branch targets |
|
| |||||
| CVTCSI 18CB | Indicator options | Receiver | Controls | Source | Indicator targets |
Operand 2: Character(15) variable scalar.
Operand 3: Character scalar.
Operand 4-5:
| Bound program access | ||||||
|---|---|---|---|---|---|---|
The return_code will be set as follows:
The receiver, controls and source parameters correspond to operands 1, 2 and 3 on the CVTCS operation. The receiver_length and source_length parameters contain the length, in bytes, of the receiver and source strings. They are expected to contain values between 1 and 32,767. The return_code parameter is used to provide support for the branch and indicator forms of the CVTCS operation. The user must specify code to process the return_code and perform the desired branching or indicator setting. |
This instruction converts the source (operand 3) from character to SNA (systems network architecture) format 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 source operand can be described by the controls operand as being one or more fixed-length data fields that may be separated by fixed-length gaps of characters to be ignored during the conversion operation. Additionally, the controls operand specifies the amount of data to be processed from the source to produce a converted record in the receiver. This may be a different value than the length of the data fields in the source. The following diagram shows this structure for the source operand.
The controls operand must be a character scalar
that specifies additional
information to be used to
control the conversion operation. The operand must be at
least 15 bytes in length and has the following format:
| Offset | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex |
| Field Name |
| Data Type and Length | ||||||||
| 0 | 0 |
| Controls operand |
| Char(15) | ||||||||
| 0 | 0 |
| Receiver offset |
| Bin(2) | ||||||||
| 2 | 2 |
| Source offset |
| Bin(2) | ||||||||
| 4 | 4 |
| Algorithm modifier |
| Char(1) | ||||||||
| 5 | 5 |
| Source record length |
| Char(1) | ||||||||
| 6 | 6 |
| Data field length |
| Bin(2) | ||||||||
| 8 | 8 |
| Gap offset |
| Bin(2) | ||||||||
| 10 | A |
| Gap length |
| Bin(2) | ||||||||
| 12 | C |
| Record separator character |
| Char(1) | ||||||||
| 13 | D |
| Prime compression character |
| Char(1) | ||||||||
| 14 | E |
| Unconverted source record bytes |
| Char(1) | ||||||||
| 15 | F |
| --- End --- |
|
| ||||||||
As input to the instruction, the source offset and receiver offset fields specify the offsets where the 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, the offset identifies a byte beyond the end of the operand and a template value invalid (hex 3801) exception is signaled. When the source offset and the receiver offset field are output from the instruction, they 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 can be specified as indicated by the bit meanings
in the following chart. At least one
of the functions must be specified. If all of the algorithm
modifier bits are zero, a template value invalid (hex 3801) exception
is signaled. The algorithm modifier
bit meanings are:
| Bits | Meaning | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| 0 |
| ||||||||
| 1-2 |
| ||||||||
| 3 |
| ||||||||
| 4-7 |
(Reserved)
|
The source record length value specifies the amount of data from the source to be processed to produce a converted record in the receiver. Specification of a source record length of zero results in a template value invalid (hex 3801) exception.
The data field length value specifies the length of the data fields in the source. Data fields occurring in the source may be separated by gaps of characters that are to be ignored during the conversion operation. Specification of a data field length of zero indicates that the source operand is one data field. In this case, the gap length and gap offset values have no meaning and are ignored.
The gap offset value specifies the offset to the next gap in the source. This value is both input to and output from the instruction. This is relative to the current byte to be processed in the source as located by the source offset value. No validation is done for this offset. It is assumed to be valid relative to the source operand. The gap offset value is ignored if the data field length is specified with a value of zero.
The gap length value specifies the amount of data that is to be ignored between data fields in the source operand during the conversion operation. The gap length value is ignored if the data field length is zero.
The record separator character value specifies the character that precedes the converted form of each record in the receiver. It also serves as a delimiter when the previous record is truncating trailing blanks. The Convert SNA to Character instruction recognizes any value that is less than hex 40. The record separator value is ignored if do not use record separators is specified in the algorithm modifier.
The prime compression character value specifies the character to be used as the prime compression character when performing compression of the source data to SNA format. It may have any value. The prime compression character value is ignored if the perform compression function is not specified in the algorithm modifier.
The unconverted source record bytes value specifies the number of bytes remaining in the current source record that are yet to be converted.
When the perform record spanning function is specified in the algorithm modifier, the unconverted source record bytes field is both input to and output from the instruction. On input, a value of hex 00 means it is the start of a new record and the initial conversion step is yet to be performed. That is, a record separator character has not yet been placed in the receiver. On input, a nonzero value less than or equal to the source record length specifies the number of bytes remaining in the current source record that are yet to be converted into the receiver. This value is assumed to be the valid count of unconverted source record bytes relative to the current byte to be processed in the source as located by the source offset value. As such, it is used to determine the location of the next record boundary in the source operand. This value must be less than or equal to the source 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 that describes the number of bytes of the current source record that have not yet been converted.
When the perform record spanning function is not specified in the algorithm modifier, the unconverted source record bytes value is ignored.
Only the first 15 bytes of the controls operand are used. Any excess bytes are ignored.
The description of the conversion process is presented as a series of separately performed steps that 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 use record separators and perform blank truncation function indicates record processing is to be performed. If this is not specified, in which case compression 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 the start of a full or partial record.
When the perform record spanning function has not been specified in the algorithm modifier, the source offset is assumed to locate the start of a record.
When the perform record spanning function has been specified in the algorithm modifier, the source offset is assumed to locate a point at which processing of a possible partially converted record is to be resumed. In this case, the unconverted source record bytes value contains the length of the remaining portion of the source record to be converted. The conversion process in this case is started by completing the conversion of the current source record before processing the next full source record.
When string processing is specified, the source offset locates the start of the source string to be converted.
Only the bytes of the data fields in the source are accessed for conversion purposes. Gaps between data fields are ignored causing the access of data field bytes to occur as if the data fields were contiguous. A string of bytes accessed from the source for a length equal to the source record length is considered to be a record for the conversion operation.
When during the conversion process, the end of the source operation is encountered, the instruction ends with a resultant condition of source exhausted.
When record processing is specified in the algorithm modifier, this check is performed at the start of conversion for each record. If the source operand does not contain a full record, the source exhausted condition is recognized. The instruction is terminated with status in the controls operand describing the last completely converted record. For source exhausted, partial conversion of a source record is not performed.
When string processing is specified in the algorithm modifier, then compression must be specified and the compression function described below defines the detection of source exhausted.
If the converted form of the source cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. 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 compression function must be specified and the conversion process proceeds with the compression 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.
A truncated record is built by logically appending the record data to the record separator value specified in the controls operand and removing all blank characters after the last nonblank character in the record. If a record has no trailing blanks, then no actual truncation takes place. A null record, a record consisting entirely of blanks, will be converted as just the record separator character with no other data following it. The truncated record then consists of the record separator character followed by the truncated record data, the full record data, or no data from the record.
If either the data transparency conversion or the compression function is specified in the algorithm modifier, the conversion process continues for this record with the next specified function.
If not, the conversion process for this record is completed by placing the truncated record into the receiver. If the truncated record cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. When the perform record spanning function is specified in the algorithm modifier, as much of the truncated record as will fit is placed into the receiver and the controls operand is updated to describe how much of the source record was successfully converted into the receiver. When the perform record spanning function is not specified in the algorithm modifier, the controls operand is updated to describe only the last fully converted record in the receiver and the value of the remaining bytes in the receiver is unpredictable.
Data transparency conversion is performed if the function is specified in the algorithm modifier. This provides for making the data in a record transparent to the Convert SNA to Character instruction in the area of its scanning for record separator values. Transparent data is built by preceding the data with 2 bytes of transparency control information. 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 ranging from 1 to 255 decimal, of the number of bytes of data that follow and is referred to as the TRN count. This contains the length of the data and does not include the TRN control information length.
Transparency conversion can be specified only in conjunction with record processing and, as such, is performed on the truncated form of the source record. The transparent record is built by preceding the data that follows the record separator in the truncated record with the TRN control information. The TRN count in this case contains the length of just the truncated data for the record and does not include the record separator character. For the special case of a null record, no TRN control information is placed after the record separator character because there is no record data to be made transparent.
If the compression function is specified in the algorithm modifier, the conversion process continues for this record with the compression function.
If not, the conversion process for this record is completed by placing the transparent record into the receiver. If the transparent record cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun.
When the perform record spanning function is specified in the algorithm modifier, as much of the transparent record as will fit is placed into the receiver and the controls operand is updated to describe how much of the source record was successfully converted into the receiver. The TRN count is also adjusted to describe the length of the data successfully converted into the receiver; thus, the transparent data for the record is not spanned out of the receiver. The remaining bytes of the transparent record, if any, will be processed as a partial source record on the next invocation of the instruction and will be preceded by the appropriate TRN control information. For the special case where only 1 to 3 bytes are available at the end of the receiver, (not enough room for the record separator, the transparency control, and a byte of data) then just the record separator is placed in the receiver for the record being converted. This can cause up to 2 bytes of unused space at the end of the receiver. The value of these unused bytes is unpredictable.
When the perform record spanning function is not specified in the algorithm modifier, the controls operand is updated to describe only the last fully converted record in the receiver and the value of the remaining bytes in the receiver is unpredictable.
Compression is performed if the function is specified in the algorithm modifier. This provides for reducing the size of strings of duplicate characters in the source data. The source data to be compressed may have assumed a partially converted form at this point as a result of processing for functions specified in the algorithm modifier. Compressed data is built by concatenating one or more compression strings together to describe the bytes that make up the converted form of the source data prior to the compression step. The bytes of the converted source data are interrogated to locate the prime compression character strings (two or more consecutive prime compression characters), duplicate character strings (three or more duplicate nonprime characters) and nonduplicate character strings occurring in the source.
The character strings encountered (prime, duplicate and nonduplicate) are reflected in the compressed data by building one or more compression strings to describe them. 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 described.
The format of an SCB and the description of the data
that may follow it are:
| Offset | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex |
| Field Name |
| Data Type and Length | ||||||||||||||||
| 0 | 0 |
| SCB |
| Char(1) | ||||||||||||||||
| 0 | 0 |
| Control |
| Bits 0-1 | ||||||||||||||||
|
|
|
|
| ||||||||||||||||||
| 0 | 0 |
| Count |
| Bits 2-7 | ||||||||||||||||
|
|
|
|
This contains the number of
characters that have been deleted for
a prime or duplicate string, or the
number of characters to the next SCB
for a nonduplicate string. A count
value of zero cannot be produced.
| ||||||||||||||||||
| 1 | 1 |
| --- End --- |
|
| ||||||||||||||||
When record processing is specified, the compression is performed as follows.
The compression function is performed on just the converted form of the current source record including the record separator character. The converted form of the source record prior to the compression step may be a truncated record or a transparent record as described above, depending upon the functions selected in the algorithm modifier. The record separator and TRN control information is always converted as a nonduplicate compression entry to provide for length adjustment of the TRN count, if necessary.
The conversion process for this record is completed by placing the compressed record into the receiver. If the compressed record cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun.
When the perform record spanning function is specified in the algorithm modifier, as much of the compressed record as will fit is placed into the receiver and the controls operand is updated to describe how much of the source record was successfully converted into the receiver. The last compression entry placed into the receiver may be adjusted if necessary to a length that provides for filling out the receiver. This length adjustment applies only to compression entries for nonduplicate strings. Compression entries for duplicate strings are placed in the receiver only if they fit with no adjustment. For the special case where data transparency conversion is specified, the transparent data being described is not spanned out of the receiver. This is provided for by performing length adjustment on the TRN count of a transparent record, which may be included in the compressed data so that it describes only the source data that was successfully converted into the receiver. For the special case where only 2 to 5 bytes are available at the end of the receiver, not enough room for the compression entry for a nonduplicate string containing the record separator and the TRN control, and up to a 2-byte compression entry for some of the transparent data, the nonduplicate compression entry is adjusted to describe only the record separator. By doing this, no more than 3 bytes of unused space will remain in the receiver. The value of these unused bytes is unpredictable. Unconverted source record bytes, if any, will be processed as a partial source record on the next invocation of the instruction and will be preceded by the appropriate TRN control information when performing transparency conversion.
When the perform record spanning function is not specified in the algorithm modifier, the controls operand is updated to describe only the last fully converted record in the receiver. The value of the remaining bytes in the receiver is unpredictable.
When string processing is specified, the compression is performed as follows.
The compression function is performed on the data for the entire source operand on a compression string basis. In this case, the fields in the controls operand related to record processing are ignored.
The conversion process for the source operand is completed by placing the compressed data into the receiver.
When the compressed data cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. As much of the compressed data as will fit is placed into the receiver and the controls operand is updated to describe how much of the source data was successfully converted into the receiver. The last compression entry placed into the receiver may be adjusted if necessary to a length that provides for filling out the receiver. This length adjustment applies only to compression entries for nonduplicate strings. Compression entries for duplicate strings are placed in the receiver only if they fit with no adjustment. By doing this, no more than 1 byte of unused space will remain in the receiver.
When the compressed data can be completely contained in the receiver, the instruction ends with a resultant condition of source exhausted. The compressed data is placed into the receiver and the controls operand is updated to indicate that all of the source data was successfully converted 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 conditions. 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 blank truncation step 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 the perform record spanning function is specified in the algorithm modifier, the unconverted source record bytes field specifies the length of the remaining source record bytes yet to be converted. When the perform record spanning function is not specified in the algorithm modifier, the unconverted source record bytes field has no meaning and is not set. The gap offset value indicates the offset to the next gap relative to the source offset value set for this condition. The gap offset value has no meaning and is not set when the data field length is zero.
The following are limits that apply to the functions performed by this instruction.
| Programming Notes: |
If the source operand does not end on a record boundary, in which case the last record is spanned out of the source, this instruction performs conversion only up to the start of that partial record. In this case, the user of the instruction must move this partial record to combine it with the rest of the record in the source operand to provide for its being processed correctly upon the next invocation of the instruction. If full records are provided, the instruction performs its conversions out to the end of the source operand and no special processing is required. 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. |
06 Addressing
08 Argument/Parameter
10 Damage Encountered
1C Machine-Dependent
20 Machine Support
22 Object Access
24 Pointer Specification
2C Program Execution
2E Resource Control Limit
32 Scalar Specification
36 Space Management
38 Template Specification
44 Protection Violation