General instructions

General hardware built-in functions are intended to provide access to general purpose instructions that are not normally generated by the compiler. For more information on these instructions, see the topic of the z/Architecture Principles of Operation.
Note: Before you use any of the instructions listed in Table 2 in your program, you must include the builtins.h header file (unless the instructions are otherwise specified) and compile the program with the LANGLVL(EXTENDED) option or the LANGLVL(LIBEXT) option.
Table 1. Standard general-instruction prototypes
PROTOTYPE and Notes Sample Pseudo Assembly MIN ARCH
int __cds1(void* Op1, void* Op2, void* Op3)
Note: The user must include stdlib.h to use this built-in function. It is similar to cds() but does not explicitly set the type to be swapped in the prototype.
 CDS Op1,Op3,Op2D(Op2B) ARCH(0)
int __cdsg(void* Op1, void* Op2, void* Op3)
Note: The user must include stdlib.h to use this built-in function. It is similar to cdsg() but does not explicitly set the type to be swapped in the prototype.
 CDSG Op1,Op3,Op2D(Op2B) ARCH(5) with LP64
int __cs1(void* Op1, void* Op2, void* Op3)
Note: The user must include stdlib.h to use this built-in function. It is similar to cs() but does not explicitly set the type to be swapped in the prototype.
 CS Op1,Op3,Op2D(Op2B) ARCH(0)
int __csg(void* Op1, void* Op2, void* Op3)
Note: The user must include stdlib.h to use this built-in function. It is similar to csg() but does not explicitly set the type to be swapped in the prototype.
 CSG Op1,Op3,Op2D(Op2B) ARCH(5) with LP64
void __dcbf(const void* Op2)

It releases the cache line containing the specified address (Op2) from all accesses.

 PFD M1,Op2
Note: M1 is a code generated by the compiler with a value of 7.
 ARCH(8)
void __dcbst(const void* Op2)

It releases the cache line containing the specified address (Op2) from store access and retains the data in the cache line for fetch access.

 PFD M1,Op2
Note: M1 is a code generated by the compiler with a value of 6.
 ARCH(8)
void __dcbt(const void* Op2)

It prefetches the cache line containing the specified address (Op2) into the cache for fetch access.

 PFD M1,Op2
Note: M1 is a code generated by the compiler with a value of 1.
 ARCH(8)
void __dcbtst(const void* Op2)

It prefetches the cache line containing the specified address (Op2) into the cache for store access.

 PFD M1,Op2
Note: M1 is a code generated by the compiler with a value of 2.
 ARCH(8)
void __pack (unsigned char *OP1, unsigned char len1, unsigned char *OP2, unsigned char len2)
  • The format of op2 is changed from zoned to signed-packed-decimal, and the result is placed at op1 location.
  • op2 is treated as having the zoned format. The numeric bits of each byte are treated as a digit. The zone bits are ignored, except the zone bits in the rightmost byte, which are treated as a sign.
  • The sign and digits are moved unchanged to op1 and are not checked for valid codes. The sign is placed in the rightmost four bit positions of the rightmost byte of the result field, and the digits are placed adjacent to the sign and to each other in the remainder of the result field.
  • The result is obtained as if the operands were processed right to left. When necessary, op2 is considered to be extended on the left with zeros. If op1 field is too short to contain all digits of op2, the remaining leftmost portion of op2 is ignored. Access exceptions for the unused portion of op2 may or may not be indicated.
  • len1 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand). The length must be in the range 0 to 15.
  • len2 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the second operand). The length must be in the range 0 to 15.
 PACK Op1D(len1,Op1B),Op2D(len2,Op2B) ARCH(0)
void __tr (unsigned char *Op1, const unsigned char *Op2, unsigned char len)
  • The bytes of op1 are used as eight-bit arguments to reference a list designated by the address of op2. Each function byte selected from the list replaces the corresponding argument in op1.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the left of the first operand used in the machine instruction.
  • The bytes of op1 are selected one by one for translation, proceeding left to right. Each argument byte is added to the initial op2 address. The addition is performed following the rules for address arithmetic, with the argument byte treated as an eight-bit unsigned binary integer and extended with zeros on the left. The sum is used as the address of the function byte, which then replaces the original argument byte.
  • The operation proceeds until the op1 field is exhausted. The list is not altered unless an overlap occurs.
  • When the operands overlap, the result is obtained as if each result byte were stored immediately after fetching the corresponding function byte.
 TR Op1D(len,Op1B),Op2D(Op2B) ARCH(0)
Table 2. Built-in general-instruction prototypes
PROTOTYPE and Notes Sample Pseudo Assembly MIN ARCH 
int __clcle(char *op1,
            unsigned long op1_len,
            unsigned char op2,
            char *op3,
            unsigned long op3_len);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction.
  • op3 and op3_len represent the third operand in the hardware instruction.
  • op2 specifies the number of bytes to pad the shorter operand on the right.

If the LP64 compiler option is in effect, the op1_len and op3_len operands are 64-bit unsigned integers. Otherwise, op1_len and op3_len are 32-bit unsigned integers.

The return value is the condition code set by the CLCLE instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1 
L R3, Op1_len 
L R4, Op3 
L R5, Op3_len 
CLCLE R2, R4, Op2D(Op2B)
ARCH(2) 
int __clclu(unsigned short *op1,
            unsigned long op1_len,
            unsigned short op2,
            unsigned short *op3,
            unsigned long op3_len);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction.
  • op2 specifies the number of bytes to pad the first operand on the right, in the event that it is shorter than the third operand.
  • op3 and op3_len represent the third operand in the hardware instruction.
Conditions:
  • If the LP64 compiler option is in effect, the op1_len and op3_len operands are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
  • If the operand values are odd numbers, a specification exception will be triggered by the hardware.
The return value is the condition code set by the CLCLU instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1
L R3, Op1_len
L R4, Op3
L R5, Op3_len
CLCLU R2, R4, Op2D(Op2B)
ARCH(6) 
int __cu12(unsigned short *op1,
           unsigned long op1_len,
           char *op2,
           unsigned long op2_len,
           char **invalid_utf8,
           unsigned char mask);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-16 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source UTF-8 characters.
  • invalid_utf8 points to a pointer field for receiving the address of the invalid UTF-8 character in the source when the condition code is "2".
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU12 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1
L R3, Op1_len
L R4, Op2
L R5, Op2_len
CU12 R2, R4, Mask
ARCH(7) 
int __cu14 (unsigned int *op1,
            unsigned long op1_len,
            char *op2,
            unsigned long op2_len,
            unsigned char **invalid_utf8,
            unsigned char mask);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-32 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source UTF-8 characters.
  • invalid_utf8 points to a pointer field for receiving the address of the invalid UTF-8 character in the source when the condition code is "2".
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU14 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1 
L R3, Op1_len 
L R4, Op2 
L R5, Op2_len 
CU14 R2, R4, Mask 
ST *invalid_utf8,R4
ARCH(7) 
int __cu21(char *op1,
           unsigned long op1_len,
           unsigned short *op2,
           unsigned long op2_len,
           unsigned char mask);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-8 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source 2-byte Unicode characters.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU21 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1
L R3, Op1_len
L R4, Op2
L R5, Op2_len
CU21 R2, R4, Mask
ARCH(7) 
int __cu24(unsigned int *op1,
           unsigned long op1_len,
           unsigned short *op2,
           unsigned long op2_len,
           usigned char mask);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-32 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source UTF-16 characters.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU24 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1
L R3, Op1_len
L R4, Op2
L R5, Op2_len
CU21 R2, R4, Mask
ARCH(7) 
int  __cu41(char *op1,
            unsigned long op1_len,
            unsigned int *op2,
            unsigned long op2_len,
            unsigned int **invalid_utf32);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-8 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source UTF-32 characters.
  • invalid_utf32 points to a pointer field for receiving the address of the invalid UTF-32 character in the source when the condition code is "2".
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU41 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1 
L R3, Op1_len 
L R4, Op2 
L R5, Op2_len 
CU41 R2, R4 
ST *invalid_utf32,R4
ARCH(7) 
int __cu42(unsigned short *op1,
           unsigned long op1_len,
           unsigned int *op2,
           unsigned long op2_len,
           unsigned int **invalid_utf32);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction. op1 points to the storage location for receiving the converted UTF-16 characters.
  • op2 and op2_len represent the second operand in the hardware instruction. op2 points to the source UTF-32 characters.
  • invalid_utf32 points to a pointer field for receiving the address of the invalid UTF-32 character in the source when the condition code is "2".
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the CU42 instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1 
L R3, Op1_len 
L R4, Op2 
L R5, Op2_len 
CU42 R2, R4 
ST *invalid_utf32, R4
ARCH(7)
int __cvb(char *op2);

op2 points to an 8-byte storage area that contains a valid packed-decimal value. The return value is the converted 32-bit signed binary integer.

 CVB R1, Op2D(Op2X, Op2B) ARCH(0)
long long __cvbg(char *op2);

Operands: op2 points to a 16-byte storage area that contains a valid packed-decimal value.

The return value is the converted 64-bit signed binary integer.

CVBG R1, Op2D(Op2X, Op2B) ARCH(5)
void __cvd(int op1, char *op2);
  • op1 is a 32-bit signed binary integer value that gets converted into a packed-decimal value.
  • op2 points to an 8-byte storage area that receives the converted packed-decimal value.
 CVD Op1, Op2D(Op2X, Op2B) ARCH(0)
void __cvdg(long long op1, char *op2);
Operands:
  • op1 is a 64-bit signed binary integer value that gets converted into a packed-decimal value.
  • op2 points to a 16-byte storage area that receives the converted packed-decimal value.
CVDG Op1, Op2D(Op2X, Op2B) ARCH(5)
int __lad(int* op1, int op3, int* op2)
Note:
  • Return value corresponds to the condition code set by LAA.
  • The location pointed to by op2 must be word aligned for __lad. Otherwise, a specification exception is recognized.
 
L R3, Op3
LAA R1, R3, Op2D(Op2B)
ST R1, *Op1
 ARCH(9)
int __ladg(long* op1, long op3, long* op2)
Note:
  • Return value corresponds to the condition code set by LAAG.
  • The location pointed to by op2 must be double-word aligned for __ladg. Otherwise, a specification exception is recognized.
 
LG R3, Op3
LAAG R1, R3, Op2D(Op2B)
STG R1, *Op1
 ARCH(9) with LP64
int __ladl(unsigned int* op1, unsigned int op3, unsigned int* op2)
Note:
  • Return value corresponds to the condition code set by LAAL.
  • The location pointed to by op2 must be word aligned for __ladl. Otherwise, a specification exception is recognized. 
L R3, Op3
LAAL R1, R3, Op2D(Op2B)
ST R1, *Op1
 ARCH(9)
int __ladlg(unsigned long* op1, unsigned long op3, unsigned long* op2)
Note:
  • Return value corresponds to the condition code set by LAALG.
  • The location pointed to by op2 must be double-word aligned for __ladlg. Otherwise, a specification exception is recognized. 
LG R3, Op3
LAALG R1, R3, Op2D(Op2B)
STG R1, *Op1
 ARCH(9) with LP64
int __lan(unsigned int* op1, unsigned int op3, unsigned int* op2)
Note:
  • Return value corresponds to the condition code set by LAN.
  • The location pointed to by op2 must be word aligned for __lan. Otherwise, a specification exception is recognized. 
L R3, Op3
LAN R1, R3, Op2D(Op2B)
ST R1, *Op1
 ARCH(9)
int __lang(unsigned long* op1, unsigned long op3, unsigned long* op2)
Note:
  • Return value corresponds to the condition code set by LANG.
  • The location pointed to by op2 must be double-word aligned for __lang. Otherwise, a specification exception is recognized. 
LG R3, Op3
LANG R1, R3, Op2D(Op2B)
STG R1, *Op1
 ARCH(9) with LP64
int __lao(unsigned int* op1, unsigned int op3, unsigned int* op2)
Note:
  • Return value corresponds to the condition code set by LAO.
  • The location pointed to by op2 must be word aligned for __lao. Otherwise, a specification exception is recognized. 
L R3, Op3
LAO R1, R3, Op2D(Op2B)
ST R1, *Op1
 ARCH(9)
int __laog(unsigned long* op1, unsigned long op3, unsigned long* op2)
Note:
  • Return value corresponds to the condition code set by LAOG.
  • The location pointed to by op2 must be double-word aligned for __laog. Otherwise, a specification exception is recognized. 
LG R3, Op3
LAOG R1, R3, Op2D(Op2B)
STG R1, *Op1
 ARCH(9) with LP64
int __lax(unsigned int* op1, unsigned int op3, unsigned int* op2)
Note:
  • Return value corresponds to the condition code set by LAX.
  • The location pointed to by op2 must be word aligned for __lax. Otherwise, a specification exception is recognized. 
L R3, Op3
LAX R1, R3, Op2D(Op2B)
ST R1, *Op1
 ARCH(9)
int __laxg(unsigned long* op1, unsigned long op3, unsigned long* op2)
Note:
  • Return value corresponds to the condition code set by LAXG.
  • The location pointed to by op2 must be double-word aligned for __laxg. Otherwise, a specification exception is recognized. 
LG R3, Op3
LAXG R1, R3, Op2D(Op2B)
STG R1, *Op1
 ARCH(9) with LP64
unsigned int __lcbb(const void* op2, unsigned short boundary)
Operands:
  • op2 represents the second operand in the hardware instruction.
  • boundary represents the boundary to encode in the hardware instruction. It must be a literal value of either 64, 128, 256, 512, 1024, 2048, or 4096.

The return value is the first operand set by the LCBB instruction. The first operand contains the number of bytes to load from the second operand location without crossing the specified block boundary. If the number of bytes is greater than 16, sixteen is placed in the first operand.

 
LCBB R1, Op2D(Op2X, Op2B),
BoundaryM
 ARCH(11)
int __lpd(unsigned int* op3, unsigned int* op4, unsigned int* op1, unsigned int* op2)
Note:
  • Return value corresponds to the condition code set by LPD.
  • The locations pointed to by op1 and op2 must be word aligned for __lpd. Otherwise, a specification exception is recognized. 
LPD R3, Op1D(Op1B), Op2D(Op2B)
ST R3, *Op3
ST R4, *Op4
 ARCH(9)
int __lpdg(unsigned long* op3, unsigned long* op4, unsigned long* op1, unsigned long* op2)
Note:
  • Return value corresponds to the condition code set by LPDG.
  • The locations pointed to by op1 and op2 must be double-word aligned for __lpdg. Otherwise, a specification exception is recognized. 
LPDG R3, Op1D(Op1B), Op2D(Op2B)
STG R3, *Op3
STG R4, *Op4
 ARCH(9) with LP64
unsigned int __lrv(unsigned int *Op)

The return value is the result.

 LRV R1, OpD(OpX,OpR) ARCH(4)
unsigned long __lrvg(unsigned long *Op)

The return value is the result.

 LRVG R1, OpD(OpX,OpR) ARCH(5) with LP64
unsigned short __lrvh(unsigned short *Op)

The return value is the result.

 LRVH R1, OpD(OpX,OpR) ARCH(4) 
int __mvcle(char *op1,
            unsigned long op1_len,
            unsigned char op2, char *op3,
            unsigned long op3_len);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction.
  • op3 and op3_len represent the third operand in the hardware instruction.
  • op2 specifies the byte for padding the first operand on the right, in the event that it is shorter than the third operand.

Conditions: If the LP64 compiler option is in effect, the op1_len and op3_len operands are 64-bit unsigned integers. Otherwise, op1_len and op3_len are 32-bit unsigned integers.

The return value is the condition code set by the MVCLE instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1 
L R3, Op1_len 
L R4, Op3 
L R5, Op3_len 
MVCLE R2, R4, Op2D(Op2B)
ARCH(2) 
int __mvclu(unsigned short *op1,
            unsigned long op1_len,
            unsigned short op2,
            unsigned short *op3,
            unsigned long op3_len);
Operands:
  • op1 and op1_len represent the first operand in the hardware instruction.
  • op2 specifies padding the first operand with 2 bytes if it is shorter than the third operand.
  • op3 and op3_len represent the third operand in the hardware instruction.
Notes:
  1. If the operand values are odd numbers, a specification exception will be triggered by the hardware.
  2. If the LP64 compiler option is in effect, the op1_len and op3_len operands are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the MVCLU instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L R2, Op1
L R3, Op1_len
L R4, Op3
L R5, Op3_len
MVCLU R2, R4, Op2D(Op2B)
ARCH(6)
int __nc (unsigned char *OP1, unsigned char *OP2, unsigned char length)
Operands:
  • Each operand is processed left to right. When the operands overlap, the result is obtained as if the operands were processed one byte at a time and each result byte were stored immediately after fetching the necessary operand bytes.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand).

The return value is the condition code.

 NC Op1D(len,Op1B),Op2D(Op2B) ARCH(0)
int __oc (unsigned char *OP1, unsigned char *OP2, unsigned char length)
Operands:
  • Each operand is processed left to right. When the operands overlap, the result is obtained as if the operands were processed one byte at a time and each result byte were stored immediately after fetching the necessary operand bytes.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand).

The return value is the condition code.

 OC Op1D(len,Op1B),Op2D(Op2B) ARCH(0)
void __pack (unsigned char *OP1, unsigned char len1, unsigned char *OP2, unsigned char len2)
Operands:
  • The format of op2 is changed from zoned to signed-packed-decimal, and the result is placed at op1 location.
  • op2 is treated as having the zoned format. The numeric bits of each byte are treated as a digit. The zone bits are ignored, except the zone bits in the rightmost byte, which are treated as a sign.
  • The sign and digits are moved unchanged to op1 and are not checked for valid codes. The sign is placed in the rightmost four bit positions of the rightmost byte of the result field, and the digits are placed adjacent to the sign and to each other in the remainder of the result field.
  • The result is obtained as if the operands were processed right to left. When necessary, op2 is considered to be extended on the left with zeros. If op1 field is too short to contain all digits of op2, the remaining leftmost portion of op2 is ignored. Access exceptions for the unused portion of op2 may or may not be indicated.
  • len1 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand). The length must be in the range 0 to 15.
  • len2 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the second operand). The length must be in the range 0 to 15.
 PACK Op1D(len1,Op1B),Op2D(len2,Op2B) ARCH(0)
void __pka(char *op1, char *op2, unsigned char op2_len);
  • op1 points to a 16-byte storage area. The packed string is stored in the storage addressed by op1.
  • op2 points to an ASCII string to be packed by the operation.
  • op2_len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the second operand).
    Notes:
    1. If op2_len is not between 0 and 31, a specification exception will be triggered by the hardware.
    2. If op2_len is not a literal, the compiler will issue an EX instruction that executes a target PKA instruction with op2_len encoded in the register used by the EX instruction. 
PKA Op1D(Op1B),
 Op2D(Op2_len, Op2B)
ARCH(6)
void __pku(char *op1, unsigned short *op2, unsigned char op2_len);
  • op1 points to a 16-byte storage area. The packed string is stored in the storage addressed by op1.
  • op2 points to Unicode Basic Latin character string to be packed by the operation.
  • op2_len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the second operand.
    Notes:
    1. If op2_len is not an odd number between 0 and 63, a specification exception will be triggered by the hardware.
    2. If op2_len is not a literal, the compiler will issue an EX instruction that executes a target PKU instruction with op2_len encoded in the register used by the EX instruction. 
PKU Op1D(Op1B),
 Op2D(Op2_len, Op2B)
ARCH(6)
unsigned long __popcnt(unsigned long op);

The population count instruction counts the number of bits set in each byte of a register. It then sets the corresponding byte of the result register to reflect the count.

The instruction operates on all 64-bits of a register and thus clobbers the upper half of a register in 32-bit mode. Volatile registers R0, R1, or R15 are used for the instruction in 32-bit mode with NOHGPR.

 POPCNT R1, op ARCH(9) 
int __srstu (unsigned short *op1,
             unsigned short *op2,
             unsigned short pattern,
             unsigned short **found_char);
Operands:
  • op1 represents the first operand in the hardware instruction, it points at the first 2-byte character after the end of the second operand.
  • op2 represents the second operand in the hardware instruction, it points at the start of a 2-byte character string.
  • pattern is the 2-byte character to be searched for.
  • found_char points to a pointer field for receiving the address of the 2-byte character that was found in the second operand.
The return value is the condition code set by the SRSTU instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L GR0, pattern
L R1, Op1
SRSTU R1, Op2
ST *found_char, R1
ARCH(7)
int __stck(unsigned long long *Op1)

The return value is the condition code.

 STCK Op1D(Op1B) ARCH(0)
int __stcke(void *Op1)

The return value is the condition code.

 STCKE Op1D(Op1B) ARCH(4)
int __stckf(unsigned long long *Op1)

The return value is the condition code.

 STCKF Op1D(Op1B) ARCH(7)
void __strv(unsigned int Op1, unsigned int *Op2) STRV R1, Op2D(Op2X,Op2R) ARCH(4)
void __strvg(unsigned long Op1, unsigned long *Op2)

STRVG R1, Op2D(Op2X,Op2R) ARCH(5) with LP64
void __strvh(unsigned short Op1,unsigned short *Op2) STRVH R1, Op2D(Op2X,Op2R) ARCH(4)
void __tr (unsigned char *Op1, const unsigned char *Op2, unsigned char len)
Operands:
  • The bytes of op1 are used as eight-bit arguments to reference a list designated by the address of op2. Each function byte selected from the list replaces the corresponding argument in op1.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the left of the first operand used in the machine instruction.
  • The bytes of op1 are selected one by one for translation, proceeding left to right. Each argument byte is added to the initial op2 address. The addition is performed following the rules for address arithmetic, with the argument byte treated as an eight-bit unsigned binary integer and extended with zeros on the left. The sum is used as the address of the function byte, which then replaces the original argument byte.
  • The operation proceeds until the op1 field is exhausted. The list is not altered unless an overlap occurs.
  • When the operands overlap, the result is obtained as if each result byte were stored immediately after fetching the corresponding function byte.
 TR Op1D(len,Op1B),Op2D(Op2B) ARCH(0) 
int __tre(char *op1,
          unsigned long op1_len,
          char *op2,
          unsigned char test_char);
Operands:
  • op1 represents the first operand in the hardware instruction. It points to the byte string that needs to be translated.
  • op1_len specifies the length of the first operand.
    Note: If the LP64 compiler option is in effect, the op1_len operand is a 64-bit unsigned integer. Otherwise it is a 32-bit unsigned integer.
  • op2 represents the second operand in the hardware instruction. It points to a 256-byte translation table.
  • test_char specifies the terminating character in the first operand for stopping the operation.
The return value is the condition code set by the TRE instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
TRE R1, Op2
ARCH(5) 
int __troo (char *op1, char *op2,
            unsigned long op2_len,
            char *tr_table,
            unsigned char test_char,
            unsigned char mask);
Operands:
  • op1 represents the first operand in the hardware instruction.
  • op2 and op2_len represent the second operand in the hardware instruction.
    Note: If option LP64 is specified, op2_len is a 64-bit unsigned integer and the length of the first operand is considered the same as that of the second operand. If option LP64 is not specified, both operands are 32-bit unsigned integers.
  • tr_table points to a 256-byte translation table on a double-word boundary.
    Note: It is the user's responsibility to provide a double-word aligned translation table.
  • test_char specifies a 1-byte function character that can be coded in the translation table for stopping the operation.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
The return value is the condition code set by the TROO instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L GR0, test_char  
L GR1, tr_table   
L R2, Op1   
L R3, Op2_len   
TROO R2, Op2, Mask
ARCH(7) 
int __trot(unsigned short *op1, char *op2,
           unsigned long op2_len,
           char *tr_table,
           unsigned short test_char,
           unsigned char mask);
Operands:
  • op1 represents the first operand in the hardware instruction.
  • op2 and op2_len represent the second operand in the hardware instruction.
    Note: If option LP64 is specified, op2_len is a 64-bit unsigned integer and the length of the first operand is considered the same as that of the second operand. Otherwise, both operands are 32-bit unsigned integers.
  • tr_table points to a 512-byte translation table on a double-word boundary.
    Note: It is the user's responsibility to provide a double-word aligned translation table.
  • test_char specifies a 2-byte function character that can be coded in the translation table for stopping the operation.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
The return value is the condition code set by the TROT instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L GR0, test_char 
L GR1, tr_table 
L R2, Op1 
L R3, Op2_len 
TROT R2, Op2, Mask
ARCH(7) 
int __trto(char *op1, unsigned short *op2,
           unsigned long op2_len,
           char *tr_table,
           char test_char,
           unsigned char mask);
Operands:
  • op1 represents the first operand in the hardware instruction.
  • op2 and op2_len represent the second operand in the hardware instruction.
  • tr_table points to a 64-KB translation table on a double-word boundary.
    Note: It is the user's responsibility to provide a double-word aligned translation table.
  • test_char specifies a 1-byte function character, that can be coded in the translation table, for stopping the operation.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
Note: If option LP64 is specified, both op1_len and op2_len are 64-bit unsigned integers. Otherwise they are 32-bit unsigned integers.
The return value is the condition code set by the TROT instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L GR0, test_char 
L GR1, tr_table 
L R2, Op1 
L R3, Op2_len 
TRTO R2, Op2, Mask
ARCH(7)
int __trt (unsigned char *OP1, const unsigned char *OP2, unsigned char len, unsigned char *R2, unsigned char **R1)
Operands:
  • The bytes of op1 are used as eight-bit arguments to select function bytes from a list designated by the address of op2. The first nonzero function byte is inserted in general register 2, and the related argument address in general register 1.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the left of the first operand used in the machine instruction.
  • The bytes of op1 are selected one by one for translation, proceeding left to right. op1 remains unchanged in storage. Calculation of the address of the function byte is performed as in the __tr instruction. The function byte retrieved from the list is inspected for a value of zero.
  • When the function byte is zero, the operation proceeds with the next byte of op1.
  • When the function byte is nonzero, the operation is completed by inserting the function byte in general register 2 and the related argument address in general register 1. Either condition code 1 or 2 is set, depending on whether the argument byte is the rightmost byte of op1. Condition code 1 is set if one or more argument bytes remain to be translated. Condition code 2 is set if no more argument bytes remain.

The return value is the condition code.

 TRT Op1D(len,Op1B),Op2D(Op2B) ARCH(0) 
int __trtr (unsigned char *op1,
            const unsigned char *op2,
            unsigned char length,
            unsigned char *R2,
            unsigned char **R1);
Operands:
  • op1 represents the first operand in the hardware instruction; it points to the last byte of the byte string to be translated and tested.
  • op2 represents the second operand in the hardware instruction; it points to a 256-byte table.
  • length specifies the length encoded in the machine instruction (that is, the number of additional bytes to the left of the first operand used in the machine instruction; the value is between 0 and 255).
    Note: When length is not specified as a literal, an EX instruction is generated to execute a target TRTR instruction with length encoded in the register used by the EX instruction.
  • R2 points to a one-byte storage for receiving the function byte in GPR 2 when the condition code is nonzero.
  • R1 points to a pointer field for receiving the address in GPR 1 when the condition code is nonzero.
The return value is the condition code set by the TRTR instruction. 
TRTR Op1D(length, Op1B),
 Op2D(Op2B)
ST *R2, GR2
ST *R1, GR1
ARCH(7) 
int __trtt(unsigned short *op1,
           unsigned short *op2,
           unsigned long op2_len,
           char*tr_table,
           unsigned short test_char,
           unsigned char mask);
Operands:
  • op1 represents the first operand in the hardware instruction.
  • op2 and op2_len represent the second operand in the hardware instruction.
    Note: If option LP64 is specified, op2_len is a 64-bit unsigned integer and the length of the first operand is considered the same as that of the second operand. Otherwise, both operands are 32-bit unsigned integers.
  • tr_table points to a 128-KB translation table on a double-word boundary.
    Note: It is the user's responsibility to provide a double-word aligned translation table.
  • test_char specifies a 2-byte function character that can be coded in the translation table for stopping the operation.
  • mask specifies the mask encoded in the machine instruction; it must be a literal value of either 0 or 1.
The return value is the condition code set by the TRTT instruction.
Note: When the condition code is 3, the condition is handled by the compiler-generated code.
 
L GR0, test_char 
L GR1, tr_table 
L R2, Op1 
L R3, Op2_len 
TRTT R2, Op2, Mask
ARCH(7)
void __unpk (unsigned char *OP1, unsigned char len1, unsigned char *OP2, unsigned char len2)
Operands:
  • The format of op2 is changed from signed-packed-decimal to zoned, and the result is placed at op1 location.
  • op2 is treated as having the signed-packed-decimal format. Its digits and sign are placed unchanged in op1 location, using the zoned format. Zone bits with coding of 1111 are supplied for all bytes except the rightmost byte, the zone of which receives the sign of op2. The sign and digits are not checked for valid codes.
  • The result is obtained as if the operands were processed right to left. When necessary, op2 is considered to be extended on the left with zeros. If op1 field is too short to contain all digits of op2, the remaining leftmost portion of op2 is ignored. Access exceptions for the unused portion of op2 may or may not be indicated.
  • len1 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand). The length must be in the range 0 to 15.
  • len2 specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the second operand). The length must be in the range 0 to 15.
 UNPK Op1D(len1,Op1B),Op2D(len2,Op2B) ARCH(0)
int __unpka(char *op1, unsigned char op1_len, char *op2);
Operands:
  • op1 points to a maximum 32-byte storage area to receive the unpacked data from the second operand.
  • op1_len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand).
    Note: If op1_len is not a literal, the compiler will issue an EX instruction that executes a target UNPKA instruction with op1_len encoded in the register used by the EX instruction.
  • op2 points to a 16-byte data string that represents 31 digits and a sign.
The return value is the condition code set by the UNPKA instruction. 
UNPKA Op1D(Op1_len, Op1B),
 Op2D(Op2B)
ARCH(6)
int __unpku(unsigned short *op1, unsigned char op1_len, char *op2);
Operands:
  • op1 points to a maximum 64-byte storage area to receive the unpacked data from the second operand.
  • op1_len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand).
    Notes:
    1. If op1_len is not a literal, the compiler will issue an EX instruction that executes a target UNPKU instruction with op1_len encoded in the register used by the EX instruction.
    2. If op1_len is not an odd number between 0 and 63, a specification exception will be triggered by the hardware.
  • op2 points to a 16-byte data string that represents 31 digits and a sign.

The return value is the condition code set by the UNPKU instruction. 

UNPKU Op1D(Op1_len, Op1B),
 Op2D(Op2B)
ARCH(6)
int __xc (unsigned char *OP1, unsigned char *OP2, unsigned char length)
Operands:
  • Each operand is processed left to right. When the operands overlap, the result is obtained as if the operands were processed one byte at a time and each result byte were stored immediately after fetching the necessary operand bytes.
  • len specifies the length encoded in the machine instruction (that is, the number of additional bytes to the right of the first operand).

The return value is the condition code.

 XC Op1D(len,Op1B),Op2D(Op2B) ARCH(0)
Parent topic: Using hardware built-in functions