Convert Character to MRJE (CVTCM)

Op Code (Hex)	Extender	Operand 1	Operand 2	Operand 3	Operand [4-5]
CVTCM 108B		Receiver	Controls	Source

CVTCMB 1C8B	Branch options	Receiver	Controls	Source	Branch targets

CVTCMI 188B	Indicator options	Receiver	Controls	Source	Indicator targets

Operand 1: Character variable scalar.

Operand 2: Character(13) variable scalar.

Operand 3: Character scalar.

Operand 4-5:

Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction number.
Indicator Form-Numeric variable scalar or character variable scalar.

Bound program access

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

The return_code will be set as follows:

Return code	Meaning
`-1`	Receiver Overrun.
`0`	Source Exhausted.

The receiver, controls and source parameters correspond to operands 1, 2 and 3 on the CVTCM 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 CVTCM operation. The user must specify code to process the return_code and perform the desired branching or indicator setting.

Description

This instruction converts a string of characters to MRJE (MULTI-LEAVING remote job entry) compressed format. The operation converts the source (operand 3) from character to the MRJE compressed format under control of the controls (operand 2) and places the results in the receiver (operand 1).

The source and receiver operands must both be character strings. The source operand cannot be specified as either a signed or unsigned immediate value.

The source operand can be described through the controls operand as being composed of one or more fixed length data fields, which 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. It must be at least 13 bytes in length and have the following format:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Controls operand		Char(13)
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 control block (RCB) value		Char(1)
13	D	--- End ---

As 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 (i.e. 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 fields specify offsets that indicate how much of the operation is complete when the instruction ends.

The algorithm modifier has the following valid values:

Hex 00 = Perform full compression.
Hex 01 = Perform only truncation of trailing blanks.

The source record length value specifies the amount of data from the source to be processed. If a source record length of 0 is specified, a template value invalid (hex 3801) exception is signaled.

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, which are to be ignored during the conversion operation. Specification of a data field length of 0 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 field. 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 0.

The gap length value specifies the amount of data occurring between data fields in the source operand which is to be ignored during the conversion operation. The gap length value is ignored if the data field length is specified with a value of 0.

The record control block (RCB) value field specifies the RCB value that is to precede the converted form of each record in the receiver. It can have any value.

Only the first 13 bytes of the controls operand are used. Any excess bytes are ignored.

The operation begins by accessing the bytes of the source operand at the location specified by the source offset. This is assumed to be the start of a source record. 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 with one another. Bytes accessed from the source for the source record length are considered a source record for the conversion operation. They are converted into the receiver operand at the location specified by the receiver offset according to the following algorithm.

The RCB value is placed into the first byte of the receiver record.

An SRCB (sub record control byte) value of hex 80 is placed into the second byte of the receiver record.

If the algorithm modifier specifies full compression (a value of hex 00) then:

The bytes of the source record are interrogated to locate the blank character strings (2 or more consecutive blanks), identical character strings (3 or more consecutive identical characters), and nonidentical character strings occurring in the source. A blank character string occurring at the end of the record is treated as a special case (see following information on trailing blanks).

If the algorithm modifier specifies blank truncation (a value of hex 01) then:

The bytes of the source record are interrogated to determine if a blank character string exists at the end of the source record. If one exists, it is treated as a string of trailing blanks. All characters prior to it in the record are treated as one string of nonidentical characters.

The strings encountered (blank, identical, or nonidentical) are reflected in the receiver by building one or more SCBs (string control bytes) in the receiver to describe them.

The format of the SCBs built into the receiver is:

SCB format is o k l jjjjj

The bit meanings are:

Bit	Value	Meaning
o	0	End of record; the EOR SCB is hex 00.
	1	All other SCBs.
k	0	The string is compressed.
	1	The string is not compressed.
l		For k = 0:
	0	Blanks (hex 40s) have been deleted.
	1	Nonblank characters have been deleted. The next character in the data stream is the specimen character. For k = 1: This bit is part of the length field for length of uncompressed data.
jjjjj		Number of characters that have been deleted if k = 0. The value can be 2-31.
ljjjjj		Number of characters to the next SCB (no compression) if k = 1. The value can be 1-63. The uncompressed (nonidentical bytes) follow the SCB in the data stream.

When the end of a source record is encountered, an EOR (end of record) SCB (hex 00) is built into the receiver. Trailing blanks in a record including a record of all blanks are represented in the receiver by an EOR character. However, a record of all blanks is reflected in the compressed result by an RCB, an SRCB, a compression entry describing an 'unlike string' of one blank character, and an EOR character.

Additionally, the receiver offset, the source offset, and the gap offset are updated in the controls operand.

If the end of the source operand is not encountered, the operation then continues by reapplying the above algorithm to the next record in the source operand.

If the end of the source operand is encountered (whether or not in conjunction with a record boundary), the instruction ends with a resultant condition of source exhausted. The source offset locates the byte following the last source record for which conversion was completed. 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 0. The receiver offset locates the byte following the last fully converted record in the receiver. The value of the remaining bytes in the receiver after the last converted record is unpredictable.

If the converted form of a record cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. The source offset locates the byte following the last source record for which conversion was completed. 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 0. The receiver offset locates the byte following the last fully converted record in the receiver. The value of the remaining bytes in the receiver after the last converted record is unpredictable.

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

Resultant Conditions

Source exhausted-All complete records in the source operand have been converted into the receiver operand.
Receiver overrun-An overrun condition in the receiver operand was detected prior to processing all of the bytes in the source operand.

If source exhausted and receiver overrun occur at the same time, the source exhausted condition is recognized first. 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, and this condition will cause an exception on the next invocation of the instruction. The processing performed for the source exhausted condition provides for this case when the instruction is invoked multiple times with the same controls operand template. When the receiver overrun condition is the resultant condition, the source always contains data that can be converted.

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

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