CSRUNIC — Unicode instruction services

Description

CSRUNIC allows you to request processing of a group of instructions related to Unicode data. Unicode data uses the binary codes of the Unicode Worldwide Character Standard; these codes support the characters of most of the world's written languages. For details about the Unicode instructions, see z/Architecture Principles of Operations, SA22-7832. The CSRUNIC macro invokes the requested instructions by name, if the Unicode hardware is present. If the hardware is not present, the macro simulates the requested instructions.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and PSW key 8-15
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.
Control parameters:	None.

Programming requirements

The caller must include the CSRYUNIC macro to get a mapping for the parameter block for the requested function. The CSRYUNIC macro also includes symbolic equates for the return codes from the service.

Restrictions

None.

Input register information

Before issuing the CSRUNIC macro, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: Address of standard 72-byte save area. When not in AR-ASC mode, the area must be in the primary address space. When in AR-ASC mode, it must be in the space addressed via the ALET in access register 13.

Before issuing the CSRUNIC macro in AR-ASC mode, the caller must ensure that the following access registers (ARs) contain the specified information:

Register: Contents
13: ALET of the 72-byte save area pointed to by GPR 13.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The CSRUNIC macro is written as follows:

Syntax	Description

`name`	`name:` symbol. Begin `name` in column 1.

␢	One or more blanks must precede CSRUNIC.

CSRUNIC

␢	One or more blanks must follow CSRUNIC.

FUNCTION=MVCLU
FUNCTION=CLCLU
FUNCTION=TP
FUNCTION=PKA
FUNCTION=PKU
FUNCTION=UNPKA
FUNCTION=UNPKU
FUNCTION=TRTT
FUNCTION=TRTO
FUNCTION=TROT
FUNCTION=TROO
FUNCTION=TRE
FUNCTION=CUUTF
FUNCTION=CUTFU

,PBLOCK=`pblock`	`pblock:` RX-type address or address in register (2) - (12).

,RETCODE=`retcode`	`retcode:` RS-type address or register (2) - (12).

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the CSRUNIC macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

FUNCTION=MVCLU

FUNCTION=CLCLU

FUNCTION=TP

FUNCTION=PKA

FUNCTION=PKU

FUNCTION=UNPKA

FUNCTION=UNPKU

FUNCTION=TRTT

FUNCTION=TRTO

FUNCTION=TROT

FUNCTION=TROO

FUNCTION=TRE

FUNCTION=CUUTF

FUNCTION=CUTFU

A required parameter that designates the function to be performed.

FUNCTION=MVCLU: indicates to process an MVCLU operation.
FUNCTION=CLCLU: indicates to process a CLCLU operation.
FUNCTION=TP: indicates to process a TP operation.
FUNCTION=PKA: indicates to process a PKA operation.
FUNCTION=PKU: indicates to process a PKU operation.
FUNCTION=UNPKA: indicates to process an UNPKA operation.
FUNCTION=UNPKU: indicates to process an UNPKU operation.
FUNCTION=TRTT: indicates to process a TRTT operation.
FUNCTION=TRTO: indicates to process a TRTO operation.
FUNCTION=TROT: indicates to process a TROT operation.
FUNCTION=TROO: indicates to process a TROO operation.
FUNCTION=TRE: indicates to process a TRE operation.
FUNCTION=CUUTF: indicates to process a CUUTF operation.
FUNCTION=CUTFU: indicates to process a CUTFU operation.

,PBLOCK=pblock

A required input parameter, area that is mapped by DSECTs in macro CSRYUNIC that correlate to the function requested. The area provides the information needed by, and provided on return by, the CSRUNIC service. It should begin on a fullword boundary.

The name of the DSECT is "UNIC_" followed by the requested function (for example, UNIC_MVCLU for the MVCLU function).

To code: Specify the RX-type address, or address in register (2) - (12), of a 36-character field.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2) - (12).

ABEND codes

0C4

The user may get this completion code if a user-provided data area is not accessible.

0C6

The user may get this completion code if the instruction has been executed in the hardware and the provided data does not meet the requirements for that instruction.

For MVCLU, either the source length or target length was not even.
For CLCLU, either the source length or target length was not even.
For PKA, the source length exceeded 31.
For PKU, the source length exceeded 64 or was not even (that is, the LengthMinusOne was not odd).
For UNPKA, the target length exceeded 31.
For UNPKU, the target length exceeded 64 or was not even (that is, the LengthMinusOne was not odd).
For TRTT, the length was not even.
For TRTO, the length was not even.
For CUTFU, a bad UTF-8 character was encountered.

The user may get this completion code if the work area was not on a doubleword boundary.

Return codes

When the CSRUNIC macro returns control to your program, GPR 15 (and retcode, when you code RETCODE) contains a return code.

Return code constants are defined in macro CSRYUNIC.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code.

Table 1. Return Codes for the CSRUNIC Macro
Return Code	Equate Symbol	Meaning and Action
0	UNIC_MVCLU_RC_OpLengthsEqual	Meaning: The operand lengths were the same. Action: None required.
4	UNIC_MVCLU_RC_TargetLengthShorter	Meaning: The target operand was shorter than the source operand. Action: None required.
8	UNIC_MVCLU_RC_TargetLengthLonger	Meaning: The target operand was longer than the source operand. Action: None required.
10	UNIC_MVCLU_RC_TargetLengthNotEven	Meaning: The target operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=MVCLU when the target operand is an even number of bytes (that is, a whole number of unicode characters).
14	UNIC_MVCLU_RC_SourceLengthNotEven	Meaning: The source operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=MVCLU when the source operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_MVCLU_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_CLCLU_RC_OperandsEqual	Meaning: the two operands were equal. Action: None required.
4	UNIC_CLCLU_RC_LeftOpLessThanRight	Meaning: The left operand was less than the right operand. Action: None required.
8	UNIC_CLCLU_RC_RightOpLessThanLeft	Meaning: The right operand was less than the left operand. Action: None required.
10	UNIC_CLCLU_RC_LeftOpLengthNotEven	Meaning: The left operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=CLCLU when the left operand is an even number of bytes (that is, a whole number of unicode characters).
14	UNIC_CLCLU_RC_RightOpLengthNotEven	Meaning: The right operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=CLCLU when the right operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_CLCLU_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TP_RC_Valid	Meaning: the operand is a valid packed number. Action: None required.
4	UNIC_TP_RC_SignNotValid	Meaning: The sign of the operand was not valid. All the digits were valid. Action: None required.
8	UNIC_TP_RC_DigitNotValid	Meaning: One or more digits of the operand were not valid. The sign was valid. Action: None required.
0C	UNIC_TP_RC_SignDigitNotValid	Meaning: The sign and one or more digits of the operand were not valid. Action: None required.
1C	UNIC_TP_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_PKA_RC_OK	Meaning: The pack operation completed successfully. Action: None required.
14	UNIC_PKA_RC_SourceLengthNotValid	Meaning: The length of the source operand exceeded 32 bytes (that is, the LengthMinusOne exceeded 31). Action: Avoid calling CSRUNIC REQUEST=PKA for an operand longer than 32 bytes.
1C	UNIC_PKA_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_PKU_RC_OK	Meaning: The pack operation completed successfully. Action: None required.
14	UNIC_PKU_RC_SourceLengthNotValid	Meaning: The length of the source operand exceeded 64 bytes (that is, the LengthMinusOne exceeded 63). Action: Avoid calling CSRUNIC REQUEST=PKU for an operand longer than 64 bytes.
24	UNIC_PKU_RC_SourceLengthNotEven	Meaning: The source operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=PKU when the source operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_PKU_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_UNPKA_RC_Positive	Meaning: The operand represented a positive number. Action: None required.
4	UNIC_UNPKA_RC_Negative	Meaning: The operand represented a negative number. Action: None required.
0C	UNIC_UNPKA_RC_BadSign	Meaning: The operand did not have a valid sign. Action: None required.
14	UNIC_UNPKA_RC_TargetLengthNotValid	Meaning: The length of the target operand exceeded 32 bytes (that is, the LengthMinusOne exceeded 31). Action: Avoid calling CSRUNIC REQUEST=PKA for an operand longer than 32 bytes.
1C	UNIC_UNPKA_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_UNPKU_RC_Positive	Meaning: The operand represented a positive number. Action: None required.
4	UNIC_UNPKU_RC_Negative	Meaning: The operand represented a negative number. Action: None required.
0C	UNIC_UNPKU_RC_BadSign	Meaning: The operand did not have a valid sign. Action: None required.
14	UNIC_UNPKU_RC_TargetLengthNotValid	Meaning: The length of the target operand exceeded 64 bytes (that is, the LengthMinusOne exceeded 63). Action: Avoid calling CSRUNIC REQUEST=PKU for an operand longer than 64 bytes.
24	UNIC_UNPKU_RC_TargetLengthNotEven	Meaning: The target operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=UNPKU when the target operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_UNPKU_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TRTT_RC_TestCharNotFound	Meaning: The translation completed. The test character was not found. Action: None required.
4	UNIC_TRTT_RC_TestCharFound	Meaning: The test character was found. The operation ended at that point. Action: None required.
10	UNIC_TRTT_RC_LengthNotEven	Meaning: The operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=TRTT when the operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_TRTT_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TRTO_RC_TestCharNotFound	Meaning: The translation completed. The test character was not found. Action: None required.
4	UNIC_TRTO_RC_TestCharFound	Meaning: The test character was found. The operation ended at that point. Action: None required.
10	UNIC_TRTO_RC_LengthNotEven	Meaning: The operand was not an even number of bytes. Action: Only call CSRUNIC FUNCTION=TRTO when the operand is an even number of bytes (that is, a whole number of unicode characters).
1C	UNIC_TRTO_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TROT_RC_TestCharNotFound	Meaning: The translation completed. The test character was not found. Action: None required.
4	UNIC_TROT_RC_TestCharFound	Meaning: The test character was found. The operation ended at that point. Action: None required.
1C	UNIC_TROT_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TROO_RC_TestCharNotFound	Meaning: The translation completed. The test character was not found. Action: None required.
4	UNIC_TROO_RC_TestCharFound	Meaning: The test character was found. The operation ended at that point. Action: None required.
1C	UNIC_TROO_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_TRE_RC_TestCharNotFound	Meaning: The translation completed. The test character was not found. Action: None required.
4	UNIC_TRE_RC_TestCharFound	Meaning: The test character was found. The operation ended at that point. Action: None required.
1C	UNIC_TRE_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_CUUTF_RC_SourceExhausted	Meaning: All unicode characters in the source were converted to their UTF-8 equivalents. Action: None required.
4	UNIC_CUUTF_RC_TargetExhausted	Meaning: The target operand did not have enough room to hold the UTF-8 equivalents of all of the source unicode characters. Action: Provide a larger target area.
1C	UNIC_CUUTF_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.
0	UNIC_CUTFU_RC_SourceExhausted	Meaning: All UTF-8 characters in the source were converted to their unicode equivalents. Action: None required.
4	UNIC_CUTFU_RC_TargetExhausted	Meaning: The target operand did not have enough room to hold the unicode equivalents of all of the source UTF-8 characters. Action: Provide a larger target area.
8	UNIC_CUTFU_RC_BadUtf8Char	Meaning: A character in the source operand was not a valid UTF-8 character. Action: Make sure that the source operand contains only valid UTF-8 characters.
1C	UNIC_CUTFU_RC_WorkareaNotAligned	Meaning: The workarea provided was not on a doubleword boundary. Action: Make sure that the workarea is on a doubleword boundary.

Examples

Operation:

Execute a MVCLU operation.

The code is as follows.

      LA    2,MYPBLOCK               Get address of parm
      USING UNIC_MVCLU,2
      XC    UNIC_MVCLU(UNIC_MVCLU_LEN),UNIC_MVCLU Clear block
*                                       Also includes ALETs
      MVC   UNIC_MVCLU_TARGETADDR,TARGADDR Set target area
      MVC   UNIC_MVCLU_TARGETLEN,TARGLEN   Set target length
      MVC   UNIC_MVCLU_SOURCEADDR,SOURCEADDR Set source area
      MVC   UNIC_MVCLU_SOURCELEN,SOURCELEN   Set source length
      MVC   UNIC_MVCLU_PAD,PADCHAR         Set pad char
      LA    3,WORKAREA
      ST    3,UNIC_MVCLU_WORKAREAADDR Set workarea address
      CSRUNIC  FUNCTION=MVCLU,PBLOCK=UNIC_MVCLU
      DROP  2
 .
 .
         DS    0F        Align parameter on word boundary
MYPBLOCK DS    (UNIC_MVCLU_LEN)CL1 PBLOCK parameter
TARGADDR DS    A         Output target area
TARGLEN  DS    F         Length of target area
SOURCEADDR DS  A         Input source area
SOURCELEN DS   F         Length of source area
PADCHAR  DC    XL2'4040' Pad with X'4040'
         DS    0D        Doubleword align workarea
WORKAREA DS    CL512     Work area