AS400 MI Functional Reference-SC41-8226-02 text

Application System/400 Machine Interface Functional Reference Version 2 SC41 -8226-02 !l«u|i Application System/400 Machine Interface Functional Reference Version 2 SC41 -8226-02 Third Edition (November 1993) The functions described publication apply to the in this IBM AS/400 machine interface. Order publications through your IBM representative or the IBM branch serving your stocked at the address given below. A Customer Satisfaction Feedback form form has been removed, you for readers' comments may address your comments to: is locality. Publications are not provided at the back of this publication. If the Attn Department 245 IBM Corporation 3605 Highway 52 N Rochester, MN 55901-7899 or you can fax your USA comments to: United States and Canada: 800 + 937-3430 Other countries: ( + 1 + 507 + 253-51 92 When you send information way it believes appropriate to IBM, you grant IBM a non-exclusive right to use or distribute the information without incurring any obligation to you or restricting your use of it. in © Copyright International Business Machines Corporation 1991, 1993. All rights reserved. Note to U.S, Government Users — Documentation related to restricted rights - Use, duplication or disclosure subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. any is Special Notices References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program or other IBM product state or imply that only IBM's in this publication is not intended to program or other product may be used. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577. The following terms, denoted by an asterisk (*) in this publication, are trademarks of the IBM Corpo- ration in the United States and/or other countries: AS/400 Application System/400 IBM 400 This publication could contain technical inaccuracies or typographical errors. The information herein is subject to change. iii Contents Special Notices HI About This Manual Who Should Use This Manual What You Should Know How This Manual Is Organized v v v v Overview Chapter Introduction 1. ^ Format Conventions Used of the operand syntax Instruction Definition In This Manual <|_ 2 <l _3 Basic Function Instructions Chapter 2. Computation and Branching Instructions 2-1 Add Logical Character (ADDLC) Add Numeric (ADDN) And (AND) Branch 2-3 2-6 2 -io (B) ' ‘ Clear Bit in String (CLRBTS) ' ’ 2 -i 5 ^ Compare Bytes Left-Adjusted (CMPBLA) Compare Bytes Left-Adjusted with Pad (CMPBLAP) Compare Bytes Right-Adjusted (CMPBRA) Compare Bytes Right-Adjusted with Pad (CMPBRAP) Compare Numeric Value (CMPNV) Compress Data (CPRDATA) Compute Array Index (CAI) Compute Math Function Using One Input Value (CMF1) Compute Math Function Using Two Input Values (CMF2) ’ © ^ ’ ’ 2 -i 7 2-19 ' 2 -21 ' ’ 2 -23 2-25 2-28 2-30 2-32 ’ Concatenate (CAT) Convert BSC to Character (CVTBC) Convert Character to BSC (CVTCB) Convert Character to Hex (CVTCH) Convert Character to MRJE (CVTCM) Convert Character to Numeric (CVTCN) Convert Character to SNA (CVTCS) Convert Decimal Form to Floating-Point (CVTDFFP) Convert External Form to Numeric Value (CVTEFN) Convert Floating-Point to Decimal Form (CVTFPDF) Convert Hex to Character (CVTHC) Convert MRJE to Character (CVTMC) Convert Numeric to Character (CVTNC) Convert SNA to Character (CVTSC) Copy Bits Arithmetic (CPYBTA) Copy Bits Logical (CPYBTL) Copy Bits with Left Logical Shift (CPYBTLLS) Copy Bits with Right Arithmetic Shift (CPYBTRAS) Copy Bits with Right Logical Shift (CPYBTRLS) Copy Bytes Left-Adjusted (CPYBLA) 2-13 ' ’ ’ ’ ’ ’ ’ ' ’ ’ ’ 2 -41 2-46 ’ ’ ' 2 -48 ’ 2-52 ’ ' ’ ’ ’ ’ 2 _ 55 ^ ’ 2-57 2-62 2 -65 2-74 2 -76 ' ’ ’ 2 -79 ’ 2-82 ’ 2-84 ' ’ 2-88 2-90 2-100 ’ ‘ ’ ' 2 -102 ^ 2-104 ’ ' ’ ' ^ ' 2-106 ' 2-108 ‘ ‘ ’ ^ 2 -1 10 Copyright IBM Corp. 1991, 1993 j v Copy Bytes Left-Adjusted with Pad (CPYBLAP) Copy Bytes Overlap Left-Adjusted (CPYBOLA) Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) Copy Bytes Repeatedly (CPYBREP) Copy Bytes Right-Adjusted (CPYBRA) Copy Bytes Right-Adjusted with Pad (CPYBRAP) Copy Bytes to Bits Arithmetic (CPYBBTA) Copy Bytes to Bits Logical (CPYBBTL) Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) Copy Hex Digit Numeric to Numeric (CPYHEXNN) Copy Hex Digit Numeric to Zone (CPYHEXNZ) Copy Hex Digit Zone To Numeric (CPYHEXZN) Copy Hex Digit Zone To Zone (CPYHEXZZ) Copy Numeric Value (CPYNV) Decompress Data (DCPDATA) 2-112 Divide (DIV) 2-146 Divide with 2-114 2-116 2-118 2-120 2-122 2-124 2-126 2-128 2-132 2-134 2-136 2-138 2-140 2-143 2-150 Remainder (DIVREM) Edit (EDIT) 2-154 Exchange Bytes (EXCHBY) 2-162 Exclusive Or (XOR) 2-164 Extended Character Scan (ECSCAN) Extract Exponent (EXTREXP) Extract Magnitude (EXTRMAG) Multiply (MULT) Negate (NEG) Not (NOT) Or (OR) Remainder (REM) Scale (SCALE) Scan (SCAN) Scan with Control (SCANWC) Search (SEARCH) Set Bit in String (SETBTS) 2-167 Set Instruction Pointer (SETIP) 2-214 Store and Set Computational Attributes (SSCA) 2-216 Subtract Logical Character (SUBLC) 2-220 Subtract Numeric (SUBN) 2-223 Test and Replace Characters (TSTRPLC) 2-227 Test Bit in String Test Bits Under 2-171 2-174 2-177 2-181 2-184 2-187 2-190 2-194 2-198 2-201 2-209 2-212 2-229 (TSTBTS) 2-231 Mask (TSTBUM) 2-233 Translate (XLATE) 2-235 Translate with Table (XLATEWT) Translate with Table and DBCS Skip (XLATWTDS) Trim Length (TRIML) Verify (VERIFY) Date/Time/Timestamp Instructions External Data Formats Date, Time, and Timestamp Concepts Compute Date Duration (CDD) Compute Time Duration (CTD) Compute Timestamp Duration (CTSD) Convert Date (CVTD) Convert Time (CVTT) Convert Timestamp (CVTTS) Chapter 2-237 2-240 2-242 3-1 3. 3-3 3-3 3-13 3-16 3-19 3-22 3-25 3-28 Contents V Decrement Date (DECD) Decrement Time (DECT) Decrement Timestamp (DECTS) 3.3^ 3.35 3_ 3 g Increment Date (INCD) Increment Time (INCT) Increment Timestamp (INCTS) Chapter 4 | . 3-42 3. 46 3 _ 49 Pointer/Name Resolution Addressing Instructions 4_-| Compare Pointer for Object Addressability (CMPPTRA) Compare Pointer for Space Addressability (CMPPSPAD) Compare Pointers for Equality (CMPPTRE) Compare Pointer Type (CMPPTRT) Copy Bytes with Pointers (CPYBWP) ’’’’’’’ ' 4 _7 4-9 4-12 Resolve Data Pointer (RSLVDP) Resolve System Pointer (RSLVSP) 4 .^ 4 Set Space Pointer from Pointer (SETSPPFP) Set System Pointer from Pointer (SETSPFP) 4 _22 Chapter 5 4 .^7 ’ Space Addressing Instructions Add Space Pointer (ADDSPP) Compare Space Addressability (CMPSPAD) . Set Space Pointer (SETSPP) Set Space Pointer with Displacement (SETSPPD) Set Space Pointer Offset (SETSPPO) 5.^ ’ ‘ ' ’ ' ' ‘ ' ’ ' ' 5.5 '''5.7 ’ ’ 5.9 ’ ’ ’ ’ ' 5.^ ’ ’ ’ ^ ^ ' 5_ 5_1 8 (SUBSPPFO) ' 5 . 20 ’ 5 . 22 ’ 5 . 24 Chapter 6. Space Management Instructions Create Space (CRTS) 0_1 6 _3 Space Attributes (MATS) Modify Space Attributes (MODS) ’ Materialize | | | | | | | | 6-11 0. 15 . Allocate Chapter | ’ Heap Management Instructions Heap Space Storage (ALCHSS) Create Heap Space (CRTHS) Destroy Heap Space (DESHS) Free Heap Space Storage (FREHSS) Free Heap Space Storage From Mark (FREHSSMK) Materialize Heap Space Attributes (MATHSAT) Reallocate Heap Space Storage (REALCHSS) Set Heap Space Storage Mark (SETHSSMK) Chapter 7 7.3 7 _6 7^-, ’’’’’’’’ 8. 7 . 22 g.-j ' 8_ 3 ^ 8 . 24 Program Execution Instructions Program (ACTPG) External (CALLX) . ’ g.^ ' Activate g _3 ^ 9. 5 Call Internal (CALLI) Clear Invocation Exit (CLRIEXIT) 7 . 17 7 . 25 Program Management Instructions Bound Program (MATBPGM) Materialize Program (MATPG) Call 7.^3 7 . 15 ’’’’’’’ ’’’’’’’’’’ Materialize Chapter 9 u 5_16 Store Space Pointer Offset (STSPPO) Subtract Space Pointer Offset (SUBSPP) Subtract Space Pointers For Offset 4.24 5_3 Set Data Pointer (SETDP) Set Data Pointer Addressability (SETDPADR) Set Data Pointer Attributes (SETDPAT) | 4.3 4_5 ’ ’ g_ g ^ 9-11 Contents vi Deactivate Program 9-12 (DEACTPG) End (END) 9-14 (MATACTAT) Materialize Activation Group Attributes (MATAGPAT) Modify Automatic Storage Allocation (MODASA) 9-15 Return External (RTX) 9-25 Set Argument List Length (SETALLEN) 9-27 Set Invocation Exit (SETIEXIT) Store Parameter List Length (STPLLEN) 9-29 Transfer Control (XCTL) 9-33 Materialize Activation Attributes | | 9-19 9-23 9-31 10-1 Chapter 10. Program Creation Control Instructions No Operation (NOOP) No Operation and Skip (NOOPS) Override Program Attributes (OVRPGATR) 10-3 10-4 10-5 11-1 Chapter 11. Independent Index Instructions Create Independent Index (CRTINX) Destroy Independent Index (DESINX) Find Independent Index Entry (FNDINXEN) Insert Independent Index Entry (INSINXEN) Materialize Independent Index Attributes 11-3 11-10 11-12 11-16 11-19 (MATINXAT) 11-23 Modify Independent Index (MODINX) Remove Independent Index Entry (RMVINXEN) Chapter 12. Queue Management 11-26 12-1 Instructions 12-3 Dequeue (DEQ) Enqueue (ENQ) Materialize Queue Attributes (MATQAT) Materialize Queue Messages (MATQMSG) 12-9 12-12 12-16 Chapter 13. Object Lock Management Instructions Lock Object (LOCK) Lock Space Location (LOCKSL) Materialize Data Space Record Locks (MATDRECL) Materialize Process Locks (MATPRLK) Materialize Process Record Locks (MATPRECL) 13-1 13-3 13-8 13-13 13-17 13-20 13-24 (MATSELLK) Transfer Object Lock (XFRLOCK) Unlock Object (UNLOCK) Unlock Space Location (UNLOCKSL) Materialize Selected Locks Management Instructions (MATEXCPD) Modify Exception Description (MODEXCPD) Retrieve Exception Data (RETEXCPD) Chapter 14. Exception 13-27 13-30 13-33 .... 14-1 14-3 Materialize Exception Description 14-6 14-9 Return From Exception (RTNEXCP) 14-12 Sense Exception Description (SNSEXCPD) Signal Exception (SIGEXCP) Test Exception (TESTEXCP) 14-15 Chapter 15. | Materialize 14-19 14-24 Queue Space Management Instructions Process Message (MATPRMSG) 15-1 15-3 | Contents vii Extended Function Instructions Chapter Context Management Instructions 16. Materialize Context Chapter 17. ’’’’’’’’’’ (MATCTX) Management Instructions (MATAU) Authority List (MATAL) Authorized Objects (MATAUOBJ) Authorized Users (MATAUU) User Profile (MATUP) Authorization Materialize Authority Materialize Materialize Materialize Materialize Ig.-I 16 . 3 ’’’’’’’’ 17 _3 ’ ’ 17 . 7 ^ 17-12 17 _ 2 o ’ ’ ’ ’ ’ ’ ’ 17 . 25 ’ ’ Test Authority (TESTAU) Test Extended Authorities (TESTEAU) ’ ' 17 . 2 g ^ 17-34 Chapter | 18. Process Management Instructions Materialize Process Activation Groups (MATPRAGP) Materialize Process Attributes (MATPRATR) Wait -Ig.-j ’ ’ ' ‘ ‘ ’ ' ’ ' ' 18 . 5 ‘ ' ’ On Time (WAITTIME) ’ ' 18 . 1g ^ Chapter 19. Resource Management Instructions Ensure Object (ENSOBJ) -jg.-l ^g_ 3 Materialize Access Group Attributes (MATAGAT) Materialize Resource Management Data (MATRMD) ' 20. Materialize Dump Space Management Dump Space (MATDMPS) ^g. 31 Instructions 20-1 ’ ’ 20-3 ^ Chapter | 21. Materialize | Machine Observation Instructions Number (FNDRINVN) Instruction Attributes (MATINAT) Invocation (MATINV) Invocation Attributes (MATINVAT) Invocation Entry (MATINVE) Invocation Stack (MATINVS) Pointer (MATPTR) Pointer Locations (MATPTRL) System Object (MATSOBJ) 21-1 Find Relative Invocation Materialize Materialize Materialize Materialize Materialize Materialize Materialize 1g . 5 ig.g Set Access State (SETACST) Chapter 18 _ 3 21-3 2 i-8 ’ ’ ’ ' ’ ’ ’ 2 i-U ’ ’ 21 . 18 21-28 ' ' 21 . 32 ^ 21 _ 37 21-46 21-48 Chapter 22, Machine Interface Support Functions Instructions Materialize Machine Attributes (MATMATR) Materialize Machine Data (MATMDATA) 22-1 22-4 2 2-30 Instruction support interfaces Chapter Machine 23. Exception Specifications 23-1 Interface Exception Data Exception 23-2 List 23.3 Appendix A. Instruction Summary Instruction Stream Syntax A_ 3 Index v Contents „ viii About This Manual has not been submitted to The information contained in AS/400 Machine Interface Functional Reference either expressed or warranty any without any formal IBM test and is distributed on an 'as is' basis Code (VLIC) and Integrated Licensed Vertical implied. This manual is written for release 3 of AS/400 may not discuss all the functions available on your AS/400 system. The AS/400 Machine Interface Functional Reference defines the AS/400 Machine instructions and exceptions. This manual may refer to products that are Who Should Use This manual is announced but are Interface to not yet available. This Manual experience on intended for knowledgeable system programmers having substantial AS/400 computer systems. What You Should Know languages, assembly languages of other computers, and capability-based computer understand instruction set architectures. The reader would do well to study The reader should know one more high level architectures. The reader should be familiar with AS/400 objects and How This Manual Is Organized The AS/400 Machine Interface Functional Reference 1. their intended use. organized into three parts: is Basic Function Instructions most programs executing These instructions provide a basic set of functions commonly needed by to experience less tend they on the machine. Because of the basic nature of these instructions, function extended change in their operation in different machine implementations than the instructions. 2. Extended Function Instructions used to control and monitor instructions provide an extended set of functions which can be nature of these instructions, they the operation of the machine. Because of the more complicated implementations than the are more exposed to changes in their operation in different machine These basic function instructions. 3. Instruction Support Interfaces This part of the document defines those portions functions or data used pervasively on all of the instructions. It Machine Interface which provide support for discusses the exceptions and program objects which can be operated on by instructions. © Copyright IBM Corp. 1991, 1993 ix Overview © Copyright IBM Corp. 1991, 1993 Introduction Chapter Introduction 1. This chapter contains the following: Detailed descriptions of the AS/400 » machine interface instruction fields and the formats of these fields • A description of the format used « A list of the terms You should read Instruction this in in describing each instruction the syntax that define the characteristics of the operands chapter in its entirety before attempting to write instructions. Operands Each instruction requires from zero to four operands. Each operand may consist of one or more fields or a reference to an ODT that contain either a null operand specification, an immediate data value, template. If the version object. The size of the operand field depends on the version of the program is 1, the size of the operand the size of the operand field is 2 bytes. If the version number is number 0, field is 3 bytes. Operands: Certain instructions allow certain operands to be null. means that some optional function of the instruction is not to be performed Null In general, a null operand or that a default action is to be performed by the instruction. Immediate Operands: The value of this type of operand Immediate operands may have the following values: is encoded in the instruction operand. • Signed binary -representing a binary value of negative 4096 to positive 4095. • Unsigned binary -representing a binary value of 0 to 8191. • Byte string • Absolute instruction number-representing an instruction number . Relative instruction tion in - representing a single byte value from hex 00 to hex FF. number- representing in the range of 1 to 8191. a displacement of an instruction relative to the instrucmay identify an instruction displacement of which the operand occurs. This operand value negative 4096 to positive 4095. Object References: This type of operand contains a reference (possibly qualified) to an operands or compound object in the ODT. Operands that are ODT object references may be simple ODT operands. Simple Operands: The value encoded in the operand refers to a specific object defined Simple operands consist of a single 2-byte operand entry. in the ODT. consists of a primary (2-byte) operand and a series of primary operand is an ODT reference to a base object The operands. one to three secondary (2-byte) to the base object. qualifiers while the secondary operands serve as Compound Operands: A compound operand A compound operand may have • the following uses: Subscript references element of a data object array, a pointer array, or an instruction definition list may be to referenced with a subscript compound operand. The operand consists of a primary reference array. of the element to an value index the specify to operand secondary the array and a An © individual Copyright IBM Corp. 1991, 1993 1-1 introduction Substring references • A portion of a character scalar data object may compound operand. The operand substring be referenced as an instruction operand through a consists of a primary operand to reference the base string object and secondary references to specify the value of an index (position) and a value for the length of the substring. The length secondary operand field can specify whether to allow or not allow for a null substrinq reference (a length value of zero). • base references Explicit An instruction operand may specify an explicit override for the base pointer for a based data object or a based addressing object. The operand consists of a primary operand reference to the based object and a secondary operand reference to the pointer on which to base the object for this operand. The override is in effect for the single operand. The displacement implicit in the ODT definition of the primary operand and the addressability contained in the explicit pointer are combined to provide an address for the operand. The explicit base may be combined with either the subscript or the substring compound operands to compound operand or a based substring compound operand. provide a based subscript Format Conventions Used Instruction The user section. In This Manual of this manual must be aware that not every instruction uses every field described Only the information pertaining to the fields that are used by an instruction is each in this provided for instruction. In this manual, each instruction Following this is is formatted with the instruction name followed by its base mnemonic, the operation code (op code) in hexadecimal and the number of operands with their general meaning. Example: ADD NUMERIC (ADDN) Op Code (Hex) Operand Su ™ 1043 This information later in this is Operand 1 Addend 2 1 Operand 3 Addend 2 followed by the operands and their syntax. See “Definition of the Operand Syntax” for a detailed discussion of the syntax of instruction operands. chapter Example: Operand 1: Operand 2: Numeric scalar. Operand 3: Numeric scalar. Numeric variable ILE access — scalar. . A description of the parameters for Integrated Language Environment access to the instruction is given. See the corresponding ILE language reference manual for details as to how this information should be interpreted for a given language. Chapter! Introduction 1-2 Introduction A Description: detailed description and a functional definition of the instruction is given. follows: term def : The terms are defined or fields in a template are described, they are highlighted as as follows: term highlighted it is to, nition. When a term is referenced or a value of a field is refered i reference. defined in the template. a template are generally described in the same order as they are so they may not field, related other However, some fields are more appropriately described with Fields in appear in exact order. operands Authorization Required: A list of the object authorization required for each of the given. is instruction instruction or for any objects subsequently referenced by the Lock Enforcement: in the Describes the specification of the lock states that are to be enforced during execution of the instruction. The following states Enforcement • of enforcement can be specified for an instruction: for materialization system object is allowed if no other process is holding a locked exclusive no read object for (LENR) lock on the object. In general, this rule applies to instructions that access an materialization and retrieval. Access to a Enforcement • for modification read Access to a system object is allowed if no other process is holding a locked exclusive no that instructions to applies rule this general, In lock. (LEAR) read allow (LENR) or locked exclusive object. system modify or alter the contents of a Enforcement of object control • another process is holding any lock on the system object. rule applies to instructions that destroy or rename a system object. Access Limitations: prohibited is if These are the limits that In general, this apply to the functions performed by the instruction. standard operation Resultant Conditions: These are the conditions that can be set at the end of the order to perform a conditional branch or set a conditional indicator. in The “exceptions” sections contain a list of exceptions that can be caused by the exception by the exception instruction. Exceptions related to specific operands are indicated for each applies to the under the heading operand. An entry under the word, other, indicates that the exception Exceptions: instruction but not to a particular operand. A detailed description of exceptions Definition of the is in Chapter 23, “Exception Specifications” on page 23-1. operand syntax are the Syntax consists of the allowable choices for each instruction operand. The following terms used in the syntax and the meanings of those terms: • Numeric: Numeric attribute of binary, packed decimal, zoned-decimal, or floating-point • Character • Scalar: : common character attribute - Scalar data object that — Constant scalar object is not an array (see note 1) Chapter 1. Introduction 1-3 Introduction - Immediate operand (signed or unsigned) - Element of an - Substring of a array of scalars (see notes 1 and 2) character scalar or a character scalar constant data object (see notes 1 and 3) Data Pointer Defined Scalar: - A scalar defined by a data pointer - Substring of a character scalar defined by a data pointer (see notes 1 and 3) Pointer: - Pointer data object that - Array: An array Data Pointer: Same A 2) is the instruction is the operand 1) as scalar except constant scalar objects and immediate operand values are pointer data object that the operand If 1 of scalars or an array of pointers (see note excluded. If and 1) pointer machine object Variable Scalar: - not an array (see note Element of an array of pointers (see notes - Space - is is to be used as a data pointer. a source operand, the pointer storage form must contain a data pointer executed. a receiver operand, a data pointer is constructed by the instruction its current contents (see note 4). is in when the specified area regardless of Space Pointer: A space pointer data object or a space pointer machine object. Space Pointer Data Object: A pointer data object - the operand If when - to be used as a space pointer. must contain a space pointer If the operand is a receiver operand, a space pointer is constructed by the instruction specified area regardless of its current contents (see note 4). If the operand instruction - is a source operand, the pointer storage form the instruction is executed. is System Pointer: a pointer data object - that If is is that is in the to be used as a system pointer. a source operand, the specified area must contain a system pointer when the executed. the operand is a receiver operand, a system pointer is constructed by the instruction its current contents (see note 4). in the specified area regardless of Relative Instruction Number: Instruction Number: Unsigned immediate operand. A Instruction Pointer: - the operand is the instruction is If Signed immediate operand. pointer data object that is to be used as an instruction pointer. a source operand, the specified area must contain an instruction pointer executed. when If the operand is a receiver operand, an instruction pointer is constructed by the instruction the specified area regardless of its current contents (see notes 4 and in 5). Instruction Definition List Element: An entry in an instruction definition list that can be used as a branch target. A compound subscript operand form must always be used (see note 5). Chapter 1 . Introduction 1-4 Introduction Notes: 1. An operand in which the primary operand is a scalar or a pointer may also have an which an explicit base pointer is specified. instruction operand form in See “ODT Object References” A compound 2. earlier chapter for more information on compound operands. in this may be used subscript operand to select a specific element from an array of scalars or from an array of pointers. See “ODT Object references” 3. A compound earlier substring operand in this chapter for more information on compound operands. may be used to define a substring of a character scalar, or a character constant scalar object. substring operand that disallows a null substring reference (a length value of zero) may, unless precluded by the particular instruction, be specified for any operand syntactically defined as allowing a character scalar. A compound substring operand that allows a null substring A compound re ference may be specified for an operand syntactically defined as allowing a character scalar only the instruction specifies that it is allowed. Whether a compound substring operand does or does not allow a null substring reference is controlled through the specification of the length secondary if operand field. See “ODT Object References” 4. A compound act as the earlier in this chapter for more information on compound operands. may be used to select an element from an array of pointers an instruction. See “ODT Object References” earlier in this chapter for subscript operand form operand for to more information on compound operands. 5. subscript forms are not allowed on branch target operands that are used for conditional branching. Selection of elements of instruction pointer arrays and elements of instruction definition lists may, however, be referenced for branch operands by the branch instruction. Compound Alternate choices of operand types and the allowable variations within each choice are indicated syntax descriptions as shown in the following example. Operand 1: Numeric variable Operand 2: Numeric Operand 3: Instruction tion When scalar. number, branch point or instruction 1 a length is Any 2 pointer.. must be numeric. Operand 3 can be an instruc- the syntax for the operand, character scalar operands must be at least excess beyond that required by the instruction is ignored. specified the size specified. the scalar. must be variable scalar. Operands 1 and number, branch point or instruction pointer. Operand in in Scalar operands that are operated on by instructions requiring 1-byte operands, such as pad values or indicator operands, can be greater than 1 byte in length; however, only the first byte of the character string is used. The remaining bytes are ignored by the instruction. Chapter 1. Introduction 1-5 Basic Function Instructions instructions provide a Basic set of functions commonly needed by most programs executing on Because of the basic nature of these instructions, they tend to experience less change in machine. the their operation in different machine implementations than the extended function instructions. Therefore, it is recommended that, where possible, programs be limited to using just these basic function instructions to minimize the impacts which can arise in moving to different machine implementations. These © Copyright IBM Corp. 1991, 1993 Computation and Branching Instructions Chapter 2. Computation and Branching Instructions This chapter describes arranged in “Instruction all the instructions used for computation and branching. alphabetic order. For an alphabetic summary of all These instructions are the instructions, see Appendix A, Summary.” Add Logical Character (ADDLC) Add Numeric (ADDN) And (AND) 2-10 Branch 2-13 Clear 2-3 2-6 (B) Bit in String 2-15 (CLRBTS) Compare Bytes Left-Adjusted (CMPBLA) Compare Bytes Left-Adjusted with Pad (CMPBLAP) Compare Bytes Right-Adjusted (CMPBRA) Compare Bytes Right-Adjusted with Pad (CMPBRAP) Compare Numeric Value (CMPNV) Compress Data (CPRDATA) Compute Array Index (CAI) Compute Math Function Using One Input Value (CMF1) Compute Math Function Using Two Input Values (CMF2) 2-17 Concatenate (CAT) Convert BSC to Character (CVTBC) Convert Character to BSC (CVTCB) Convert Character to Hex (CVTCH) Convert Character to MRJE (CVTCM) 2-46 © 2-21 2-23 2-25 2-28 2-30 2-32 2-41 2-48 2-52 2-55 2-57 Character to Numeric (CVTCN) Character to SNA (CVTCS) 2-62 Decimal Form to Floating-Point (CVTDFFP) External Form to Numeric Value (CVTEFN) 2-74 Form (CVTFPDF) Hex to Character (CVTHC) MRJE to Character (CVTMC) Numeric to Character (CVTNC) SNA to Character (CVTSC) Bits Arithmetic (CPYBTA) Bits Logical (CPYBTL) Bits with Left Logical Shift (CPYBTLLS) Bits with Right Arithmetic Shift (CPYBTRAS) Bits with Right Logical Shift (CPYBTRLS) Bytes Left-Adjusted (CPYBLA) Bytes Left-Adjusted with Pad (CPYBLAP) Bytes Overlap Left-Adjusted (CPYBOLA) 2-79 Convert Convert Convert Convert Convert Convert Convert Convert Convert Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy Copy 2-19 2-65 Floating-Point to Decimal Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) 2-76 2-82 2-84 2-88 2-90 2-100 2-102 2-104 2-106 2-108 2-110 2-112 2-114 2-116 Bytes Repeatedly (CPYBREP) 2-118 Bytes Right-Adjusted (CPYBRA) 2-120 (CPYBRAP) (CPYBBTA) Arithmetic Logical (CPYBBTL) Bytes Right-Adjusted with Pad 2-122 Bytes to Bits 2-124 Bytes to Bits Extended Characters Left-Adjusted With Pad (CPYECLAP) Copyright IBM Corp. 1991, 1993 2-126 2-128 2-1 Computation and Branching Instructions Copy Hex Digit Numeric to Numeric (CPYHEXNN) Copy Hex Digit Numeric to Zone (CPYHEXNZ) Copy Hex Digit Zone To Numeric (CPYHEXZN) Copy Hex Digit Zone To Zone (CPYHEXZZ) Copy Numeric Value (CPYNV) Decompress Data (DCPDATA) 2-132 2-134 2-136 2-138 2-140 2-143 Divide (DIV) Divide with 2-146 Remainder (DIVREM) 2-150 Edit (edit) 2-154 Exchange Bytes (EXCHBY) Exclusive Or (XOR) Extended Character Scan (ECSCAN) Extract Exponent (EXTREXP) Extract Magnitude (EXTRMAG) Multiply (MULT) Negate (NEG) 2-162 2-164 2-167 2 -171 2-174 2-177 ' Not (NOT) ' ' ' ' 2-181 ' ’ 2-184 i 0r (OR) Remainder (REM) 2-187 2-190 Scale (SCALE) 2-194 Scan (SCAN) Scan with Control (SCANWC) Search (SEARCH) Set Bit in String (SETBTS) 2-198 2-201 2-209 2-212 Set Instruction Pointer (SETIP) Store and Set Computational Attributes (SSCA) Subtract Logical Character (SUBLC) Subtract Numeric (SUBN) 2-214 2-216 2-220 2-223 Test and Replace Characters (TSTRPLC) Test Bit in String (TSTBTS) Test Bits Under 2-227 2-229 Mask (TSTBUM) 2-231 Translate (XLATE) | Translate with Table (XLATEWT) Translate with Table and DBCS Skip Trim Length (TRIML) 2-233 2-235 (XLATWTDS) 2-237 ’’’’’’ ’’’’’’ Verify (VERIFY) ’ ’ 2-240 ’ ‘ | Chapter 2. Computation and Branching instructions 2 -242 2-2 Add Add Logical Character Op Code (ADDLC) Extender (Hex) Logical Character (ADDLC) ADDLC Operand 2 Addend 1 Operand 3 Addend 2 Operand Sum Sum Addend 1 Addend 2 Indicator targets Sum Addend 1 Addend 2 Branch targets Operand 1 [4-7] 1023 ADDLCI Indicator 1823 options ADDLCB Branch options 1C23 Operand 1: Character variable scalar (fixed-length). Operand 2: Character scalar (fixed-length). Operand 3: Character scalar (fixed-length). Operand 4-7: • Branch Form- Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code 1 Operand 2 Addend 2 Operand Sum/Addend Indicator options Sum/Addend 1 Addend 2 Indicator targets Branch options Sum/Addend 1 Addend 2 Branch targets Operand Extender (Hex) ADDLCS 1 [3-6] 1123 ADDLCIS 1923 ADDLCBS 1 D23 Operand 1: Character variable scalar (fixed-length). Operand 2: Character scalar (fixed-length). Operand 3-6 • Branch Form- Branch number. • Indicator Description: point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable The unsigned binary value of the value of the addend 2 operand and the result is addend placed operand 1 in the number, or absolute instruction scalar. is added to the unsigned binary sum operand. Operands 1, 2, and 3 must be the same length; otherwise, the Create Program instruction signals an operand length (hex 2A0A) exception. The length can be a maximum of 256 bytes. invalid performed according to the rules of algebra. The result value is then placed operand with truncating or padding taking place on the right. The pad instruction is a byte value of hex 00. The addition operation is (left-adjusted) in the receiver value used in this Chapter 2. Computation and Branching Instructions 2-3 Add Logical Character (ADDLC) If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. Resultant Conditions: The logical sum of the character scalar operands • zero with no carry out of the leftmost • not-zero with no carry • zero with carry • not-zero with carry. bit is: position Exceptions Operands Exception 06 01 08 Spacing addressing violation X X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X Argument/parameter Parameter reference violation Damage encountered Partial damage state system object damage Machine-dependent exception 03 Machine storage 22 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Other X 44 20 3 X 04 System object 1C 2 02 Boundary alignment 01 10 1 Addressing X X X X X X Program execution 04 Invalid branch target 2E Resource control limit 01 user profile storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-4 Add Logical Character (ADDLC) 12 Operands Exception 36 3 Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-5 Add Numeric (ADDN) Add Numeric (ADDN) Op Code (Hex) Extender ADDN Operand Sum Operand Addend Sum Addend Augend Sum Addend Augend Indicator targets Sum Addend Augend Indicator targets 1 Operand Augend 2 3 Operand [4-7] 1043 ADDNR 1243 ADDNI Indicator 1843 options ADDNIR Indicator 1A43 options ADDNB Branch options Sum Addend Augend Branch targets Branch options Sum Addend Augend Branch targets 1C43 ADDNBR 1 E43 Operand 1: Numeric variable scalar Operand 2: Numeric scalar Operand 3: Numeric scalar Operand 4-7: 9 Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code (Hex) Extender Operand Sum/Addend Operand Augend Sum/Addend Augend Indicator options Sum/Addend Augend Indicator targets Indicator options Sum/Addend Augend Indicator targets Branch options Sum/Addend Augend Branch targets Branch options Sum/Addend Augend Branch targets ADDNS 1 2 Operand [3-6] 1143 ADDNSR 1343 ADDNIR 1943 ADDNISR 1 B43 ADDNBS 1 D43 ADDNBSR 1 F43 Operand /. Numeric variable scalar Chapter 2. Computation and Branching Instructions 2-6 Add Numeric (ADDN) Operand 2: Operand 3-6: Numeric scalar • Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Caution: If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. Description: The Sum Operands can have is the result of adding the floating-point, Addend and Augend. packed or zoned decimal, signed or unsigned binary type. Source operands are the Addend and Augend. The receiver operand If is operands are not of the same type, addends are converted according any one of the operands has the Sum. to the following rules: addends are converted floating point type, 1. If 2. Otherwise, 3. Otherwise, the binary operands are converted to a to floating point type. if any one of the operands has zoned or packed decimal type, addends are converted packed decimal. like type. Note: to unsigned binary(2) scalars are signed binary(4) scalars. logically treated as Addend and Augend are added according to their type. Floating point operands are added using Packed decimal addends are added using packed decimal addition. Unsigned used with unsigned addends. Signed binary addends are added using two's comple- floating point addition. binary addition ment binary is addition. Better performance can be obtained if all operands have the same type. Signed and unsigned binary additions execute faster than either packed decimal or floating point additions. Decimal operands used in floating-point operations cannot contain For a decimal operation, alignment of the assumed decimal more than 15 total digit positions. point takes place by padding with 0's on the right end of the addend with lesser precision. Floating-point addition uses exponent point the is performed, right. if comparison and significand addition. Alignment of the binary necessary, by shifting the significand of the value with the smaller exponent to The exponent is increased by one for each binary digit shifted until the two exponents agree. The operation uses the lengths and the precision of the source and receiver operands accurate results. Operations performed in decimal are limited to 31 decimal to calculate digits in the intermediate result. The addition operation The is performed according to the rules of algebra. result of the operation used in is copied into the sum operand. performing the operation, the resultant value is If this operand converted to its is type. not the If same type as that necessary, the resultant value is adjusted to the length of the sum, aligned at the assumed decimal point of the sum operand, or both before being copied. If nonzero digits are truncated on the left end of the resultant value, a size (hex OCOA) exception is signaled. Chapter 2. Computation and Branching Instructions 2-7 Add Numeric (ADDN) When the target of the instruction is signed or unsigned binary size, exceptions can be suppressed. For the optional round form of the instruction, specification of a floating-point receiver operand is invalid. For fixed-point operations, if nonzero digits are truncated off the (hex OCOA) exception is signaled. left end of the resultant value, a size For floating-point operations involving a fixed-point receiver field, if nonzero digits would be truncated end of the resultant value, an invalid floating-point conversion (hex OCOC) exception is sig- off the left naled. For a floating-point sum, the exponent of the resultant value is either too large or too small to be the floating-point overflow (hex 0C06) and floating-point underflow (hex 0C07) exceptions are signaled, respectively. represented the in sum if field, a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value if the decimal value contains 15 or fewer significant nonfrac- If contains the correct truncated result only tional digits. Resultant Conditions The algebraic value of the numeric scalar sum operand • Positive • Negative • Zero 9 Unordered - - - is The algebraic value of the numeric scalar sum operand The algebraic value of the numeric scalar sum operand - The value assigned a floating-point sum operand is is positive. is negative. zero. NaN. Exceptions Operands Exception 06 3 Spacing addressing violation X X X X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X X X Argument/parameter Parameter reference violation Computation 02 Decimal data 03 Decimal point alignment 06 Floating-point overflow X 07 Floating-point underflow X 09 Floating-point invalid operand 10 Other 02 Boundary alignment 01 0C 2 Addressing 01 08 1 0A Size X 0C invalid floating-point conversion X 0D Floating-point inexact result X Damage encountered 04 System object damage X state Chapter 2. Computation and Branching Instructions 2-8 Add Numeric (ADDN) Operands Exception 44 1C Partial system object damage 1 2 3 Other X X X X Machine-dependent exception X 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X XXX XXX XXX XXX XXX Object access 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Program execution X 04 Invalid branch target 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-9 And (AND) Op Code Operand Extender (Hex) AND Operand 1 Operand 2 3 Operand [4-5] Receiver Source 1 Source 2 Receiver Source 1 Source 2 Indicator targets Receiver Source 1 Source 2 Branch targets 1093 ANDI Indicator 1893 options ANDB Branch options 1C93 _ Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3: Character scalar or numeric scalar. Operand 4-5: • Branch Form- Branch number. 8 Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code Operand Extender (Hex) Receiver/Source 1 Operand Source 2 Indicator options Receiver/Source 1 Source 2 Indicator targets Branch options Receiver/Source 1 Source 2 Branch targets ANDS 1 2 Operand [3-4] 1193 ANDIS 1993 ANDBS 1 D93 Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3-4 • Branch Form- Branch number. • Indicator Description: The Form-Numeric variable scalar or character variable The Boolean resulting string scalars. point, instruction pointer, relative instruction is AND placed in operation number, or absolute instruction scalar. performed on the string values in the source operands. The operands may be character or numeric strings. Substringing is supported for both character and is the receiver operand. They are both interpreted as bit numeric operands. The length of the operation is equal to the length of the longer of the two source operands. The shorter of the two operands is logically padded on the right with hex 00 values. This assigns hex 00 values to the results for those bytes that correspond to the excess bytes of the longer operand. The bit values of the result are determined as follows: Chapter 2. Computation and Branching Instructions 2-10 And (AND) Source The 1 Source 2 Bit Result Bit Bit 0 0 0 0 1 0 1 0 0 1 1 1 result value place on the is right. then placed (left-adjusted) The pad value used in this in the receiver operand with truncating or padding taking instruction is a byte value of hex 00. If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. Substring operand references that allow for a null substring reference (a length value of zero) may be operands 1, 2, and 3. The effect of specifying a null substring reference for either or both of the source operands is that the result is all zero and instruction's resultant condition is zero. When a null substring reference is specified for the receiver, a result is not set and the instruction's resultant condition is zero regardless of the values of the source operands. specified for When is a numeric variable scalar, it is possible that the result produced will not numeric type. This can occur due to padding with hex 00, due to truncation, or string produced by the instruction. The instruction completes normally and the receiver operand be a valid value for the due to the resultant bit signals no exceptions for these conditions. Resultant Conditions • • Zero - The value for the bit reference is Not zero The - bits of the scalar receiver operand is either all zero or a null substring specified for the receiver. bit value for the bits of the scalar receiver operand is not all zero. Exceptions Operands Exception 06 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X Addressing 01 08 Spacing addressing violation Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object damage state 44 1C Partial system object damage Machine-dependent exception 03 Machine storage 20 Other 1 limit X exceeded Machine support Chapter 2. Computation and Branching Instructions 2-11 And (AND) Operands Exception 02 Machine check 2 3 X 03 Function check 22 Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X X X X X X limit 01 user profile storage limit 36 X Program execution 04 Invalid branch target 2E Other X X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-12 Branch (B) Branch (B) Op Code Operand (Hex) 1 Branch target 1011 Operand Instruction 1: instruction definition Description: Control number, is relative instruction number, branch point, instruction pointer, or element. list unconditionally transferred to the instruction indicated in the branch target operand. The instruction number indicated by the branch target operand must be within the instruction stream containing the branch instruction. The branch target may be an element of an array of instruction pointers or an element of an instruction definition list. The specific element can be identified by using a compound subscript operand. Exceptions Operand Exception 06 X Spacing addressing violation 02 Boundary alignment violation X 03 Range X Argument/parameter 01 10 X Parameter reference violation Damage encountered 04 System object damage state 44 1C Partial system object damage 22 X X X X Machine-dependent exception 03 Machine storage 20 limit X exceeded Machine support 02 Machine check X 03 Function check X Object access Object not found X 02 Object destroyed X 03 Object suspended X 01 X 08 object compressed 24 Pointer specification 01 X Pointer does not exist X 02 Pointer type invalid 2C Program execution X 04 Invalid branch target 2E Other Addressing 01 08 1 Resource control limit Chapter 2. Computation and Branching Instructions 2-13 Branch (B) Operand Exception 01 user profile storage limit 36 1 exceeded other X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-14 Clear Bit Clear Bit Op Code Operand (Hex) String (CLRBTS) (CLRBTS) in String Operand 1 Receiver 102E in Operand 1: Character variable scalar Operand 2: Binary scalar. Description: Clears the The selected bit bit 2 Offset (fixed length) or numeric variable scalar. of the receiver operand as indicated by the from the receiver operand is set to a value of binary bit offset operand. 0. The receiver operand can be character or numeric. The leftmost bytes of the receiver operand are used in the operation. The receiver operand is interpreted as a bit string with the bits numbered left right from 0 to the total number of bits in the string minus 1. The receiver cannot be The offset a variable substring. operand indicates which indicating the leftmost bit If bit of the receiver operand is to be cleared, with a offset of zero of the leftmost byte of the receiver operand. a offset value less than zero or 3203) exception to beyond the length of the string is specified, a scalar value invalid (hex signaled. is Exceptions Operands 1 2 X X 02 Boundary alignment violation X X 03 Range X X 06 Optimized addressability invalid X X X X Exception 06 Addressing 01 08 Spacing addressing violation Argument/parameter 01 10 Parameter reference violation Damage encountered X 04 System object damage state 44 1C Partial 22 X system object damage Machine-dependent exception 03 Machine storage 20 Other limit X exceeded Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X 03 Object suspended X X X 08 object compressed Chapter 2. Computation and Branching Instructions 2-15 Clear Bit in String (CLRBTS) Operands Exception 24 1 2 X X X X 06 Invalid operand type X X 07 Invalid operand attribute 01 Pointer does not exist 02 Pointer type invalid 2A Program creation X X 08 Invalid operand value range X X 0A Invalid operand length X X 0C Invalid operand odt reference X X X X 0D Reserved 2E bits are not Resource control zero limit 01 user profile storage limit 32 exceeded X Scalar specification 01 Scalar type invalid X 03 Scalar value invalid 36 Other Pointer specification X X Space management 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-16 Compare Bytes Compare Bytes Op Code Operand Extender Branch options (Hex) operand operand Operand /: Numeric scalar or character scalar. Operand 2: Numeric scalar or character scalar. Operand 3 2 Compare [4, 5] Branch targets operand 2 1 Compare Compare Indicator options 18C2 Operand 3 Operand 1 Compare 1CC2 CMPBLAI (CMPBLA) (CMPBLA) Left-Adjusted CMPBLAB Left-Adjusted Indicator targets operand 2 1 [4, 5]: • Branch Form-Instruction number, • Indicator relative instruction number, branch Form-Numeric variable scalar or character variable point, or instruction pointer. scalar. compares the logical string values of two left-adjusted compare operands. The logical string value of the first compare operand is compared with the logical string value of the second compare operand (no padding done). Based on the comparison, the resulting condition is Description: This instruction used with the extender • field to: Transfer control conditionally to the instruction indicated in one of the branch target operands (branch form). 3 Assign a value to each of the indicator operands (indicator form). The compare operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The compare operands are compared byte by byte, from left to right with no numeric conversions performed. The length of the operation is equal to the length of the shorter of the two compare operands. The comparison begins with the leftmost byte of each of the compare operands and proceeds until all bytes of the shorter compare operand have been compared or until the first unequal pair of bytes is encountered. Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 1 and 2. The effect of specifying a null substring reference for either or both compare operands is Resultant Conditions: that the instruction's resultant condition The scalar first compare operand's is equal. string value is one of the following as compared to the second compare operand. • higher • lower • equal Exceptions Operands Exception 06 1 2 3 [4, 5] X X X X X X Other Addressing 01 Spacing addressing violation 02 Boundary alignment Chapter 2. Computation and Branching Instructions 2-17 Compare Bytes Left-Adjusted (CMPBLA) Operands Exception 08 2 3 [4, 5] X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object 44 1C Partial damage 22 state system object damage Machine-dependent exception 03 Machine storage 20 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X X X X X X limit 01 user profile storage limit 36 X Program execution 04 Branch target invalid 2E Other 1 03 Range exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-18 Compare Bytes Compare Bytes Op Code Left-Adjusted with Pad Extender Branch options (Hex) CMPBLAPB Operand CMPBLAPI 18C3 Operand 1 Compare options operand 1 operand 2 1 operand 2 Compare Operand 1: Numeric scalar or character scalar. Operand 2: Numeric scalar or character scalar. Operand 3: Numeric scalar or character scalar. Operand 4 Branch Form - Instruction number, • Indicator Description: if relative instruction Form - Numeric variable scalar or character This instruction needed). The string value of the compares the Operand 4 Pad Branch targets Pad Indicator targets number, branch [5, 6] logical string value of the first point, or instruction pointer. variable scalar. logical string values of second compare operand. with the extender field 3 Operand 3 [5, 6]: » (padded 2 Compare Indicator (CMPBLAP) (CMPBLAP) Compare operand 1CC3 Left-Adjusted with Pad two left-adjusted compare operands compare operand is compared with the logical Based on the comparison, the resulting condition is used to: Transfer control conditionally to the instruction indicated in one of the branch target operands (branch form). 3 Assign a value to each of the indicator operands (indicator form). The compare operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The compare operands are compared byte by byte, from left to right with no numeric conversions being performed. equal to the length of the longer of the two compare operands. The is logically padded on the right with the 1-byte value indicated in the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. The comparison begins with the leftmost byte of each of the compare operands and proceeds until all the bytes of the longer of the two compare operands have been compared or until the first unequal pair of The length of the operation is shorter of the two compare operands bytes is encountered. All excess bytes in the longer of the two compare operands are compared to the pad value. Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 1 and 2. The effect of specifying a null substring reference for one of the compare operands is that the other compare operand is compared with an equal length string of pad character values. resultant condition When is a null substring reference is specified for both compare operands, the equal. Substring operand references that allow for a null substring reference (a length value of zero) be specified for operand may not 3. Chapter 2. Computation and Branching Instructions 2-19 Compare Bytes Resultant Conditions: The scalar first compare operand's Left-Adjusted with Pad string value is (CMPBLAP) one of the following as compared to the second compare operand. higher • lower 9 equal Exceptions Operands Exception 06 08 Spacing addressing violation X X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X X X X X Argument/parameter Parameter reference violation Damage encountered Partial damage state system object damage Machine-dependent exception limit exceeded 02 Machine check X 03 Function check X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 08 object compressed X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X X X X X X X limit 01 user profile storage limit 36 X X Program execution 04 Branch target invalid 2E t X Machine support 01 24 Other 6] X 03 Machine storage 22 [5, X 44 20 4 X 04 System object 1C 3 02 Boundary alignment 01 10 2 Addressing 01 . 1 exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-20 Compare Bytes Right-Adjusted (CMPBRA) Compare Bytes Right-Adjusted (CMPBRA) Op Code Operand Extender Branch options (Hex) CMPBRAB operand operand -I8C6 Operand 1: Numeric scalar or character scalar. Operand 2: Numeric scalar or character scalar. Operand 3 3 [4, 5] Branch targets operand 2 1 Indicator targets Compare Compare Indicator options Operand 2 Compare Compare ICCg CMPBRAI Operand 1 operand 2 1 [4, 5]: • Branch Form-Instruction number, . indicator Form - Numeric relative instruction number, branch point, or instruction pointer. variable scalar or character variable scalar. compare operThis instruction compares the logical string values of two right-adjusted string value of logical the with ands. The logical string value of the first compare operand is compared condition is resulting the the second compare operand (no padding done). Based on the comparison, Description: used with the extender field to: Transfer control conditionally to the instruction indicated • in one of the branch target operands (branch form). Assign a value to each of the indicator operands (indicator form). . The compare operands can be either string or numeric. Any numeric operands are interpreted as logical character strings. numeric conversions perThe compare operands are compared byte by byte, from left to right with no two compare operands. the of shorter the of length the to equal formed. The length of the operation is and proceeds until all operands compare the each of of The comparison begins with the leftmost byte pair of bytes is unequal first until the or compared bytes of the shorter compare operand have been encountered. length value of zero) may be Substring operand references that allow for a null substring reference (a for either or both reference substring null a specifying specified for operands 1 and 2. The effect of compare operands is that the instruction's resultant condition The scalar first compare operand's the second compare operand, Resultant Conditions: pared to • higher • lower • equal is equal. string value is one of the following as com- Exceptions Operands Exception 06 1 2 3 [4, 5] X X X X X X Other Addressing 01 Spacing addressing violation 02 Boundary alignment violation Chapter 2. Computation and Branching Instructions 2-21 Compare Bytes XXX XXX XXX XXX XXX 1 03 Range 06 Optimized addressability invalid Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object 44 1C Partial damage state system object damage 2 X X X Object access 01 XXX XXX XXX XXX xxx Object not found 02 Object destroyed 03 Object suspended 08 object compressed Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X X limit 01 user profile storage limit 36 X Program execution 04 Branch target invalid 2E X Machine support 03 Function check 24 X Machine-dependent exception 02 Machine check 22 Other 3 [4, 5] 03 Machine storage limit exceeded 20 (CMPBRA) Operands Exception 08 Right-Adjusted exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-22 Compare Bytes Compare Bytes Right-Adjusted Op Code Extender Branch options (Hex) CMPBRAPB with Pad Operand operand 1CC7 CMPBRAPI Indicator Compare 18C7 options operand Operand 4 3 [5, 6] Pad Branch targets Pad Indicator targets operand 2 1 Compare operand 2 1 Operand V. Numeric scalar or character scalar. Operand 2: Numeric scalar or character scalar. Operand 3: Numeric scalar or character scalar. Operand 4 Operand 2 Compare Compare (CMPBRAP) (CMPBRAP) Operand 1 Right-Adjusted with Pad [5, 6]: . Branch Form-Instruction number, . Indicator Form - Numeric number, branch relative instruction point, or instruction pointer. variable scalar or character variable scalar. operThis instruction compares the logical string values of the right-adjusted compare the with compared is ands (padded if needed). The logical string value of the first compare operand condition resulting the logical string value of the second compare operand. Based on the comparison, Description: used with the extender is • field to: Transfer control conditionally to the instruction indicated in one of the branch target operands (branch form). . Assign a value to each of the indicator operands (indicator form). The compare operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The compare operands are compared byte by byte, from left to right with no numeric conversions performed. The length of the operation is equal to the length of the longer of the two compare operands. The value indicated in shorter of the two compare operands is logically padded on the left with the 1-byte byte is used. The leftmost its only length, byte in 1 more than is operand the pad operand. If the pad excess bytes Any operands. compare the longer of the byte of comparison begins with the leftmost bytes are other All value. pad the with compared (on the left) in the longer compare operand are until proceeds operation The operand. compare compared with the corresponding bytes in the other all bytes in the longer operand are compared or until the first unequal pair of bytes is encountered. value of zero) may be Substring operand references that allow for a null substring reference (a length for one of the reference substring null a specified for operands 1 and 2. The effect of specifying string of pad length equal an with compared operands is that the other compare operand is compare character values. resultant condition When is a null substring reference is specified for both compare operands, the equal. zero) Substring operand references that allow for a null substring reference (a length value of be specified for operand may not 3. Chapter 2. Computation and Branching Instructions 2-23 Compare Bytes Resultant Conditions: The scalar first compare operand's Right-Adjusted with Pad string value is pared to the second compare operand. • higher • lower • equal (CMPBRAP) one of the following as com Exceptions Operands Exception 2 1 3 4 [5, Other 6] 06 Addressing 01 08 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X X X X X Argument/parameter Parameter reference violation 01 10 Spacing addressing violation Damage encountered 04 System object 44 1C Partial damage state system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 X Machine support 02 Machine check X 03 Function check 22 X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X X X X X X X X limit 01 user profile storage limit 36 X Program execution 04 Branch target invalid 2E X exceeded Space management 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-24 Compare Numeric Value (CMPNV) Compare Numeric Value (CMPNV) Op Code Operand Extender Branch options (Hex) CMPNVB operand 1C46 operand 1846 Operand 1: Numeric scalar. Operand 2: Numeric scalar. Operand 3 Operand 2 Operand 3 Compare Branch targets [4-6] operand 2 1 Indicator targets Compare Compare Indicator options CMPNVI 1 Compare operand 2 1 [4-6]: • Branch Form - Instruction number, • Indicator Form - Numeric relative instruction number, branch point, or instruction pointer. variable scalar or character variable scalar. The numeric value of the first compare operand is compared with the signed or unsigned numeric value of the second compare operand. Based on the comparison, the resulting condition is used with the extender field to: Description: • Transfer control conditionally to the instruction indicated in one of the branch target operands (branch form). • Assign a value to each of the indicator operands (indicator form). with 0's on For a decimal operation, alignment of the assumed decimal point takes place by padding the right end of the compare operand with lesser precision. Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. operation both operands are signed numeric or both are unsigned numeric, the length of the equal to the length of the longer of the two compare operands. When is signed numeric and the other operand unsigned numeric, the unsigned operand current size. The length of the operation is is converted to a signed value with more precision than its value will equal to the length of the longer of the two compare operands. A negative signed numeric always be less than a positive unsigned value. When one operand is denormalized Floating-point comparisons use exponent comparison and significand comparison. For a been norfirst number had denormalized the floating-point number, the comparison is performed as if malized. For floating-point, two values compare unordered when at least one comparand compares unordered with everything including another NaN value. Floating-point is NaN. Every NaN comparisons ignore the sign of zero. Positive zero always compares equal with negative zero. operand (hex 0C09) exception is signaled when two floating-point values and no branch or indicator option exists for any of the unordered, negation of compare unordered unordered equal, or negation of equal resultant conditions. A floating-point invalid When a comparison is made between a floating-point compare operand and a fixed-point decimal compare operand that contains fractional digit positions, a floating-point inexact result (hex OCOD) exception may be signaled because of the implicit conversion from decimal to floating-point. Chapter 2. Computation and Branching Instructions 2-25 Compare Numeric Value (CMPNV) Resultant Conditions » High-The • Low-The • Equal-The • Unordered-The first first compare operand has a higher numeric value than the second compare operand. compare operand has a lower numeric value than the second compare operand. first compare operand has first compare operand a equal is numeric value than the second compare operand. unordered compared second compare operand. to the Exceptions Operands Exception 06 01 08 2 3 [4-6] Spacing addressing violation X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X 02 Decimal data X X 03 Decimal point alignment X X Parameter reference violation Computation 09 Floating-point invalid operand 0D 10 X X Floating-point inexact result X Damage encountered 04 System object 44 1C Partial damage state system object damage X X X X X X X X Machine-dependent exception 03 Machine storage limit exceeded 20 X Machine support 02 Machine check X 03 Function check 22 X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C X X X X X X Program execution 04 Branch target invalid 2E Other Argument/parameter 01 OC 1 Addressing Resource control X limit Chapter 2. Computation and Branching Instructions 2-26 Compare Numeric Value (CMPNV) Operands 1 Exception 01 user profile storage limit 36 2 3 [4-6] Other X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-27 Compress Data (CPRDATA) Compress Data (CPRDATA) Op Code (Hex) Operand 1 Compress Data 1041 template Operand Space : pointer. — ILE access ' | 1 CPRDATA ( compress_data_template I Description: The space pointer : compresses user data of a specified length. Operand 1 identifies compressed. The template also identifies the result space instruction plate which identifies the data to be a tem- to receive the compressed data. The Compress Data template must be aligned on a 16-byte boundary. The format Source length is as follows: Bin(4) Result area length Bin(4) Actual result length Bin(4)* Compression algorithm Bin(2) 1 = Simple TERSE algorithm = IBM LZ1 algorithm 2 Reserved (binary 0) Char(18) Source space pointer Space pointer Result space pointer Space pointer The input value associated with template entries annotated with an asterisk (*) are ignored by the instruction; these fields are updated by the instruction to return information about instruction execution. Note: The data at the location specified length compressed and stored is lenfltll is set to the number by the source space pointer for the length specified by the source by the result space point er The actual result at the location specified of bytes in the compressed The source data result. is not modified. The value of both the source length field and result area length field must be greater than zero. If the compressed result is longer than the result area (as specified by the result area length) the compression is stopped and only result area length bytes are stored. , — The mpression algorithm field specifies the algorithm used to compress the data. The IBM LZ1 algorithm tends to produce better compression on shorter input strings than the simple TERSE algorithm The algorithm choice is stored in the compressed output data so the Decompress Data instruction will automatically select the correct decompression algorithm. ' Only scalar (non-pointer) data destroyed in the output of the is compressed, so any pointers Decompress Data in the data to be compressed are instruction. Chapter 2. Computation and Branching Instructions 2-28 Compress Data (CPRDATA) Authorization Required ° None Lock Enforcement • None Exceptions Operands Exception 06 X X X 03 range X 06 optimized addressability invalid X Argument/Parameter X Parameter reference violation Damage encountered 44 1C space addressing violation 02 boundary alignment 01 10 Other Addressing 01 08 1 partial X system object damage Machine-dependent exception X 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X Object access 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control limit X X X exceeded X space extension/truncation X Template specification X 01 template value invalid 44 X Space management 01 38 X limit 01 user profile storage 36 X Domain 01 object X domain error Chapter 2. Computation and Branching Instructions 2-29 Compute Array Index Compute Array index Op Code (CAI) Operand (Hex) 1044 (CAI) 1 Array index Operand 2 Subscript A Operand 3 Operand 4 Subscript B Dimension Operand 1: Operand 2: Binary(2) scalar. Operand 3: Binary(2) scalar. Operand 4: Binary(2) constant scalar object or immediate operand. Binary(2) variable scalar. Description: This instruction provides the ability to reduce multidimensional array subscript values which can then be used in referencing the single-dimensional arrays of the This index value is computed by performing the following arithmetic operation on the indi- into a single index value system. cated operands. - Array Index = Subscript A + ((Subscript B-1) X Dimension) The numeric value of the subscript B operand is decreased by 1 and multiplied by the numeric value of the dimension operand. The result of this multiplication is added to the subscript A operand and the sum is placed in the array index operand. the operands must be binary with any implicit conversions occurring according to the rules of arithmetic operations. The usual rules of algebra are observed concerning the subtraction, addition, and multiplication of operands. All This instruction provides for mapping multidimensional arrays to single-dimensional arrays. The elements of an array with the dimensions (dl, d2, d3, ..., dn) can be defined as a single-dimensional array with d1*d2*d3*...*dn elements. To reference a specific element of the multidimensional array with subscripts (s1,s2,s3,.,.sn), it is necessary to convert the multiple subscripts to a single subscript for use in the single-dimensional AS/400 array. This single subscript can be computed using the following: sl+((s2-l)*dl) + (s3-l)*dl*d2)+... + ((sn-l)*d*d2*d3*...*dm) where m = The CAI n-1 instruction is used to form a single index value from two subscript values. To reduce N subuses of this instruction are necessary. script values into a single index value, N-1 Assume that SI, S2, and S3 are three subscript values and that Dl is the size of one dimension, D2 is the size of the second dimension, and the D1D2 is the product of Dl and D2. The following two uses of this instruction reduce the three subscripts to a single subscript. CAI INDEX, SI, S2, Dl Calculates sl+(s2-l)*dl CAI INDEX, INDEX, S3, D1D2 Calculates sl+(s2-l) *dl+(s3-l)*d2*dl Exceptions Operands Exception 06 1 2 3 4 Other Addressing 01 Spacing addressing violation X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X Chapter 2. Computation and Branching Instructions 2*30 Compute Array Index (CAI) Operands Exception 08 Parameter reference violation Partial damage state system object damage X X X X X X X X X X X X X Machine-dependent exception 03 Machine storage 22 X Damage encountered 44 20 4 X size 04 System object 1C 3 Computation 0A 10 2 Argument/parameter 01 0C Other 1 limit X exceeded Machine support 02 Machine check X 03 Function check X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-31 Compute Math Function Using One Compute Math Function Using One Op Code CMF1 (Hex) Operand Extender Input Value (CMF1) Input Value (CMF1) 1 Operand Operand 2 3 Operand [4-5] Receiver Controls Source Branch options Receiver Controls Source Branch targets CMF1I Indicator Receiver Controls Source Indicator targets 180B options 100B CMF1B 1C0B Operand 1: Operand 2: Character{2) scalar (fixed length). Operand 3: Numeric Operand 4-5: Numeric variable scalar. scalar. • Branch Form- Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. The mathematical function, indicated by the controls operand, operand value and the result is placed in the receiver operand. Description: The calculation The is always done result of the operation is in is performed on the source floating-point. copied into the receiver operand. The controls operand must be a character scalar that specifies which mathematical function performed. It must be at least 2 bytes in length and has the following format: • Controls operand — — — — — — — — — — — — — — — to be Char(2) Hex 0001 = Sine Hex 0002 = Arc sine Hex 0003 = Cosine Hex 0004 = Arc cosine Hex 0005 = Tangent Hex 0006 = Arc tangent Hex 0007 = Cotangent Hex 0010 = Exponential function Hex 0011 = Logarithm based e (natural logarithm) Hex 0012 = Sine hyperbolic Hex 0013 = Cosine hyperbolic Hex 0014 = Tangent hyperbolic Hex 0015 = Arc tangent hyperbolic Hex 0020 = Square root All other values are reserved The controls operand mathematical functions are as • is follows: Hex 0001-Sine The sine of the numeric value of the source operand, whose value is computed and placed in the receiver operand. Chapter 2. is considered to be in radians, Computation and Branching Instructions 2-32 Compute Math Function Using One The -1 result < is in the range: < SIN(x) Input Value (CMF1) 1 Hex 0002-Arc sine The arc sine of the numeric value placed The in result -pi/2 < operand of the source computed and the is result (in radians) is the receiver operand. is in the range: < ASIN(x) +pi/2 Hex 0003-Cosine The cosine of the numeric value of the source operand, whose value radians, is computed and placed in the receiver operand. The -1 result < is in < COS(x) is considered to be in the range: 1 Hex 0004- Arc cosine The arc cosine of the numeric value of the source operand is placed The 0 < in result is computed and the result (in radians) the receiver operand. is in ACOS(x) < the range: pi Hex 0005-Tangent The tangent of the source operand, whose value the result The result -infinity is placed is in < in is considered to be in radians, is computed and the receiver operand. the range: < TAN(x) +infinity Hex 0006-Arc tangent The arc tangent of the source operand is computed and the result (in radians) is placed in the receiver operand. The result -pi/2 < is in the range: ATAN(x) < pi/2 Hex 0007-Cotangent The cotangent of the source operand, whose value the result The is result -infinity placed is in < in is considered to be in radians, is computed and the receiver operand. the range: COT(x) < Hex 0010-Exponential +infinity function The computation e power (source operand) is performed and the result is placed in the receiver operand. The 0 < result is in < EXP(x) the range: +infinity Hex 0011-Logarithm based e (natural logarithm) The natural logarithm of the source operand is computed and the result is placed in the receiver operand. The result -infinity is in < the range: LN(x) < +infinity Chapter 2. Computation and Branching Instructions 2-33 Compute Math Function Using One Hex 0012-Sine hyperbolic • The sine hyperbolic of the numeric value of the source operand radians) The placed is result < is < SINH(x) Hex 0013-Cosine hyperbolic radians) The placed is result < +1 computed and the < +infinity Hex 0014-Tangent hyperbolic radians) The -1 result < placed is is in TANH(x) is computed and the result (in the receiver operand. in the range: < +1 Hex 0015-Arc tangent hyperbolic The inverse of the tangent hyperbolic of the numeric value of the source operand the result The result -infinity • result (in the range: is in COSH(x) is the receiver operand. in The tangent hyperbolic of the numeric value of the source operand • result (in +infinity The cosine hyperbolic of the numeric value of the source operand • computed and the the receiver operand. in the range: is in -infinity • Input Value (CMF1) (in radians) is in < is placed in ATANH(x) < +infinity root The square root of the numeric value of the source operand operand. 0 < result is in SQRT(x) < computed and the range: Hex 0020-Square The is the receiver operand. is computed and placed in the receiver the range: +infinity The following chart shows some special cases for certain arguments (X) of the different mathematical functions. Chapter 2. Computation and Branching Instructions 2-34 Compute Math Function Using One Input Value (CMF1) Maximum Minimum + infinity -infinity +0 -0 Value Value Other Function NaN Unmasked NaN Sine g A(e) A(f) A(f) +0 -0 A(1,f) A(1,f) B(3) Arc sine g A(e) A(f) A(f) +0 -0 A(6,f) A(6,f) - Cosine g A(e) A(f) A(f) +1 +1 A(1,f) A(1,f) B(3) Arc cosine g A(e) A(f) A(f) -R pi/2 + pi/2 A(6,f) A(6,f) - Tangent g A(e) A(f) A(f) +0 -0 A(1,f) A(1,f) B(3) Arc tangent g A(e) + pi/2 -pi/2 +0 -0 - - - Cotangent g A(e) A(f) A(f) -R inf -inf A(1,f) A(1,f) B(3) Exponent g A(e) -R inf +0 +1 +1 C(4,a) D(5,b) - Logarithm g A(e) -R inf A(f) -inf -inf - - A(2,f) Sine g A(e) -R inf -inf +0 -0 g A(e) -R inf +1 +1 g A(e) + -1 +0 -0 - - " Arc tangent g A(e) A(f) A(f) +0 -0 A(6,f) A(6,f) - A(e) + inf A(f) +0 -0 - - A(2,f) X Masked - hyperbolic Cosine + inf hyperbolic Tangent 1 hyperbolic hyperbolic Square root g Figure 2-1 . Special cases for arguments of CMF1 mathematical functions. Capital letters in the chart indicate the exceptions, small letters indicate the returned results, and Arabic numerals indicate the limits of the arguments (X) as defined in the following lists: A = Floating-point invalid operand (hex 0C09) exception (no result stored occurrence B = if unmasked; if masked, bit is set) Floating-point inexact result (hex OCOD) exception (result is stored whether or not exception is masked) C = Floating-point overflow (hex 0C06) exception (no result rence D = Floating-point underflow (hex 0C07) exception (no result always = Result follows the rules that depend on round b = Result is +0 c = Result is + infinity d = Result is -infinity e = Result is the = Result is the system default = inf = Result is the input Result is infinity g stored if unmasked; if masked, occur- is stored if unmasked; occurrence bit is set) a f is bit is set) mode or a denormalized value masked form of the input NaN masked NaN NaN Chapter 2. Computation and Branching Instructions 2-35 Compute Math Function Using One 1 = pi * 2**50 | | 2 = 3 4 = = 1n{2**1023) 5 = 1 6 = Argument Argument | pi * =Hex 432921FB54442D18 is in 2**26 | Input Value (CMF1) the range: -inf < x < -0 =Hex 41A921FB54442D18 Hex 40862E42FEFA39EF n(2‘*-1021 .4555) is in = Hex C086200000000000 the range: -1 < x < +1 The following chart provides accuracy data for the mathematical functions that can be invoked by this instruction. Chapter 2. Computation and Branching Instructions 2-36 Compute Math Function Using One Input Value (CMF1) Accuracy Data Sample Selection Function B Name Range Arc cosine <= 0 Arc sine -1.57 Arc tangent Arc tangent 14 -3 MAX(E) of x <= (E) SD(E) 8.26 * 10**-14 2.11 * 10**-15 3.33 * 10*‘-16 9.57 * 10**-17 1.06 * 10**-14 1.79 * 10**-15 2.77 * 10**-16 8.01 * 10**-17 2.22 * 10**-16 1.31 * 10**-16 .001 2.22 * 10**-16 1.56 * 10**-16 < = 400000 2.22 * 10**-16 1.28 * 10**-16 3.33 * 10**-16 8.39 * 10**-17 0**-1 9 1.28 * 10**-19 10**-16 8.17 * 10**-17 x 3.14 <= x <= < x < <= x <= -pi/2 1 Absolute Error Relative Error (e) 1.57 pi/2 3 hyperbolic Cosine (See Sine below) Cosine (See Sine Hyperbolic) below) hyperbolic II Cotangent 11 Exponential < = x < = 100 u .000001 < = x < = .001 u 4000 < = x < = 400000C u -10 <= x <= 300 0.5 <= x <= 1.5 -100 <= x <= 700 -100 2 Natural logarithm -10 Sine cosine <= .000001 000 x <= .000001 000 <= < = -10 x x x <= <= x <= x 10**-16 1.49 * 10**-16 10**-16 1.46 * 10**-16 10**-14 1.13 * 10**-14 10**-16 4.36 * 10**-16 5.72 * 5.70 * 2.17 * 10**-16 7.37 * 10**-17 100 <= <= * * 100 <= <= a 1.48 4.83 .33 * .001 400000 Sine/cosine 12 3.33 6.31 * 10**-16 1.97 * 10**-16 4.13 * 10**-16 1.27 * 10**-16 4.59 * 10**-16 1.54 * 10**-16 4.42 * 10**-16 1.44 * 10**-16 4.77 * 10**-16 1.43 * 10**-16 8.35 * 10*‘-16 3.87 * 10**-17 * 1 hyperbolic Square root Tangent Tangent <= -100 -10 <= x x <= <= 700 100 13 hyperbolic Figure 2-2 (Part 1 of 2). Accuracy data for CM FI mathematical functions. Chapter 2. Computation and Branching Instructions 2-37 Compute Math Function Using One Input Value (CMF1) I Algorithm Notes: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. = = = = and g(x) = ATAN(TAN(x)). and g(x) = e**(1n(e**x)). f(x) 1n(x), and g(x) = 1n(e**(1n(x))). f(x) x, and g(x) = 1n(e**x). Sum of squares algorithm. f(x) = 1, and g(x) = SIN(x))**2 + (COS(x))**2. Double angle algorithm. f(x) - SIN(2x), and g(x) = 2*(SIN(x)*COS(x)). f(x) = e(**x, and g{x) = (SQR(e**x))**2. f(x) = TAN(x), and g(x) = SIN(x) / COS(x). f(x) = x, and g(x) = ACOS(COS{x)). f(x) = x, and g(x) = ASIN(SIN(x)). f(x) = COT(x), and g(x) = COS(x) / SIN(x). f(x) = SINH(2x), and g(x) = 2*(SINH(x)*COSH(x)). f(x) = TANH(x), and g(x) = SINH(x) / COSH(x). f(x) = x, and g(x) = ATANH(TANH(x)). f(x) f(x) x, e**x, The sample input arguments were tangents of numbers, -pi/2 and +pi/2. Distribution Note: between Figure The 9 * 2-2 2 of ( Part vertical columns 2). in Accuracy data for CMFI x, uniformly distributed mathematical functions. the accuracy data chart have the following meanings: Function Name: This column identifies the principal mathematical functions evaluated with entries arranged in alphabetical order by function name. Sample Selection: This column identifies the selection of samples taken for a particular math function through the following - A: subcolumns: identifies the algorithm used against the argument, accuracy samples. The g{x), which were calculated to test for the anticipated relation where f(x) should equal g(x). An accuracy sample then, is an evaluation of the degree to which this relation held true. The algorithm used to sample the arctangent function, for example, defines g{x) to first calculate the tangent of x to provide an appropriate distribution of input arguments for the arctangent function. Since f(x) is defined simply as the value of x, the relation to be evaluated is then x = ARCTAN{TAN(x)). This type of algorithm, where a function and its inverse are used in tandem, is the usual type employed to provide the appropriate comparison values for the evaluation. numbers in this column x, to gather the refer to notes describing the functions, f(x) and - “Range of x": gives the range of x used to obtain the accuracy samples. The test values for x are uniformly distributed over this range. It should be noted that x is not always the direct input argument to the function being tested; it is sometimes desirable to distribute the input arguments in a nonuniform fashion to provide a more complete test of the function (see column D below). For each function, accuracy data is given for one or more segments within the valid range of x. In each case, the numbers given are the most meaningful to the function and range under consideration. - D: identifies the distribution of letter E indicates number * arguments input to the particular function being sampled. The an exponential distribution. The letter U indicates a uniform distribution. A refers to a note providing detailed information regarding the distribution. Accuracy Data: The maximum relative error and standard deviation of the relative error are generally useful and revealing statistics; however, they are useless for the range of a function where its value becomes zero. This is because the slightest error in the argument can cause an unpredictable fluctuation in the magnitude of the answer. When a small argument error would have this effect, the maximum absolute error and standard deviation of the absolute error are given for the range. Chapter 2. Computation and Branching Instructions 2-38 Compute Math Function Using One — Relative Error The maximum (e): and standard deviation relative error Input Value (CMF1) mean square) (root of the relative error are defined: MAX(e) = MAX( ABS((f(x) g(x) - ) / f(x))) where: MAX selects the largest of value of its argument. SD(e) = SQR( SQR where: tion of the - (E): deviation (root mean = - g(x) ) / f(x))) takes the square root of squares of arguments and ABS takes the absolute its arguments over its argument and all SUMSQ takes the summa- of the test cases. The maximum absolute error produced during the Absolute Error MAX(E) SUMSQ((f(x) (1/N) its testing and the standard square) of the absolute error are: MAX( ABS( f(x) - g(x) ) ) where: the operators are those defined above. SD(E) = SQR( SUMSQ( (1/N) f(x) - g(x) ) ) where: the operators are those defined above. The following are Limitations: limits that apply to the functions performed by this instruction. The source and receiver operands must both be specified as floating-point with the same length (4 bytes for short format or 8 bytes for long format). Resultant Conditions 9 Positive-The algebraic value of the receiver operand 9 Negative-The algebraic value of the receiver operand 9 Zero-The algebraic value of the receiver operand 9 Unordered-The value assigned to the floating-point is is is positive. negative. zero. result is NaN. 09 Exceptions Operands Exception 06 1 Spacing addressing violation 02 Boundary alignment violation 03 Range 06 Optimized addressability invalid 08 Argument/parameter 01 0C Parameter reference violation Other Computation 06 Floating-point overflow X 07 Floating-point underflow X X Floating-point invalid operand 0D 10 3 XXX XXX XXX XXX XXX Addressing 01 2 X Floating-point inexact result Damage encountered 04 System object damage X state Chapter 2. Computation and Branching Instructions 2-39 Compute Math Function Using One Input Value (CMF1) Operands Exception 44 1C 1 Partial 22 3 limit X exceeded Machine support 02 Machine check X 03 Function check X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C X X X X X X Program execution 04 Invalid branch target 2E Resource control X limit 01 user profile storage limit 02 Process storage 32 limit exceeded X exceeded X Scalar specification 01 X Scalar type invalid X X X 03 Scalar value invalid 36 Other X Machine-dependent exception 03 Machine storage 20 2 system object damage Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-40 Compute Math Function Using Two Compute Math Function Using Two Op Code Operand Extender 1 Input Values (CMF2) Input Values (CMF2) Operand 2 Operand 3 Operand 4 Operand [5-8] (Hex) CMF2 Receiver Controls Source 1 Source 2 Receiver Controls Source 1 Source 2 100C CMF2B Branch 1C0C options CMF2I Indicator 180C options Receiver 1: Numeric variable Operand 2: Character(2) scalar (fixed length) Operand 3: Numeric scalar. Operand 4: Numeric scalar. Operand 5-8: Branch Form - Branch number. • Indicator Controls Source Source 2 1 scalar. point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. The mathematical function, indicated by the controls operand, operand values and the result is placed in the receiver operand. Description: The calculation is Indicator targets Operand • Branch targets always done in is performed on the source floating-point. The controls operand must be a character scalar that specifies which mathematical function performed. It must be at least 2 bytes in length and have the following format: • Controls operand is to be Char(2) — Hex 0001 = Power (x to the y) — All other values are reserved The computation x power y, where x is the first source operand and y performed and the result is placed in the receiver operand. is the second source operand, The following chart shows some special cases for certain arguments of the power function (x**y)Within the chart, the capitalized letters X and Y refer to the absolute value of the arguments x and that is, X = |x| and Y = |y|. Chapter 2. Computation and Branching Instructions is y; 2-41 Compute Math Function Using Two y X -inf y<0 y= real 2n + eh + inf +0 + x> Bfl EH EZS + 1 + + 1 1 + 1 + 1 1 +0 1 x= + -1/2 + 1 0<X< 1 x"Y x"*Y x**Y + 1 + 1 + + 1 + 1 + X SQRT(X) 1 +i + 1 1 +i + 1 + inf 1 x = -0 0>X>-1 x**Y x**Y + SQRT(x) X + + SQRT(X) E(f) E(f) E(f) E(f) + E(f) E(f) E<g) E(g) + -1 + A(a) + A(a) + A(a) + A(a) X**Y 1 -1 + 1 A(a) A(a) -i Masked SQRT(X) 1 +0 HI A(c> + inf x**y x**y x**y + + + 1 1 x**y x**y +0 +0 x**y m +0 A(c) b + inf m Mi r A(c) B m m + A(c) 1 PB1 H A(C) +0 +0 A(C) 1 -0 -0 1 A(a) X -X**y X**y A(a) A(a) A(c) -1 + A(a) A(a) A(c) A(a) A(a) A(c) A(a> m m 1 A(a) X -X**y A(a) + A(a) -inf b b b b b A(c) A(c) A(c) A(c) A(c) A(c) power function (x**y) A(a) UnA(c) + inf -0 NaN A(c) a MBS M- NaN i 1 b X**y x” b masked inf + inf real A(C) -1 X**Y cat -0 A(a) 1 -t- y>0 wm 1 >T A{a) X**Y inf -1 1 + 1 1 u E(f) -1 1 + E(g) A(a) x = -inf + E(f) X**Y X<-1 + inf E(f) A(a) x = -1 X + 1/2 + inf + x**Y + input Values (CMF2) m i -inf A(c) + inf A(c> A(a) A(c) A(a) m A(c) A(e) A(c) A(e) A(e) NaN Figure 2-3. Special cases of the Capital letters defined in in the chart indicate the exceptions and small letters indicate the returned results as the following list: A Floating-point invalid operand (hex 0C09) exception E Divide by zero (hex OCOE) exception a Result is the system default b Result is the same NaN c Result is the same NaN masked d Result is the larger NaN e Result is the larger NAN masked f Result is + infinity g Result is -infinity masked NaN The following chart provides accuracy data for the mathematical function that can be invoked by this instruction. Chapter 2. Computation and Branching Instructions 2-42 Compute Math Function Using Two Sample Selection Input Values (CMF2) Accuracy Data Function Name Power < = * 10**-16 1.90 * 10**-16 .75 2.96 * 10’*-16 2.39 * 10*’-16 .9 1.23 * 10**-16 1.02 * 10**-16 y 330 -165 <= y < = 165 7.10 * 10"-16 3.18 * 10**-16 -57 <= y <= 57 1.75 * 10**-15 7.24 * 10**-16 712 2-4. <= SD(e) 4.99 -345 1/3 10 Figure MAX(e) y Accuracy data for CMF2 mathematical functions. The vertical • Function • Sample Selection This column identifies the selection of samples taken for the power function. The algorithm used against the arguments, x and y, to gather the accuracy samples was a test for the anticipated relation where f(x) should equal g(x,y): columns Name the accuracy data chart have the following meanings: in This column identifies the mathematical function. : : where: f (x)= x g(x,y)= (x**y)**(l/y) An accuracy sample then, is an evaluation of the degree to which this relation held true. The range of argument values for x and y were selected such that x was held constant at a particular value and y was uniformly varied throughout a range of values which avoided overflowing or underflowing the result field. The particular values selected are indicated in the subcolumns entitled x and y. • Accuracy Data: The maximum and standard deviation (root mean square) of the relaThese statistics for the relative error, (e), relative error and revealing the following subcolumns: tive error are generally useful are provided MAX(e) = in MAX( ABS( ( f(x) - g(x) ) / f(x) ) statistics. ) where: MAX selects the largest of its argument. SD(e) = SQR( (1/N) SUMSQ((f(x) - g(x) ) its arguments and ABS takes the absolute value of / f(x))) where: SQR takes the square root of its argument and SUMSQ takes the summation of the squares of its arguments over all of the test cases. Limitations: The following are limits that apply to the functions performed by this instruction. The source and receiver operands must both be specified as floating-point with the same length (4 bytes for short format or 8 bytes for long format). Resultant Conditions • Positive-The algebraic value of the receiver operand • Negative-The algebraic value of the receiver operand • Zero-The algebraic value of the receiver operand ® Unordered-The value assigned to the floating-point result is is is positive. negative. zero. Chapter is 2. NaN. Computation and Branching Instructions 2-43 Compute Math Function Using Two Input Values (CMF2) Exceptions Operands Exception 06 1 01 space addressing violation 02 boundary alignment violation 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0C 2 parameter reference violation 4 06 floating-point overflow X 07 floating-point underflow X X 0C invalid floating-point conversion X 0D floating-point inexact result X X X X X X X X 0E floating-point zero divide Damage encountered 04 System object damage state 44 1C partial 22 X system object damage X Machine-dependent exception 03 machine storage 20 limit exceeded X Machine support 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X X Program execution 04 invalid branch target 2E Resource control X limit 01 user profile storage limit 02 process storage 32 Other Computation 09 floating-point invalid operand 10 3 XXX XXX XXX XXX XXX Addressing limit X exceeded exceeded X Scalar specification X 01 scalar type invalid Chapter 2. X X X Computation and Branching Instructions 2-44 Compute Math Function Using Two 12 Input Values (CMF2) Operands Exception 03 scalar value invalid 36 3 4 Other X Space management X 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-45 Concatenate (CAT) Concatenate (CAT) Op Code (Hex) Operand fOF 3 1 Receiver Operand /: Operand 2: Character scalar. Operand 3: Character scalar. Operand 2 Source 1 Operand 3 Source 2 Character variable scalar. The character string value of the second source operand is joined to the right end of the character string value of the first source operand. The resulting string value is placed (left-adjusted) in the receiver operand. Description: — The length of the operation is equal to the length of the receiver operand with the resulting cated or is logically padded on the right end accordingly, The pad value for this instruction string trun- hex is 40. Substring operand references that allow for a null substring reference (a length value of zero) may be The effect of specifying a null substring reference for one source 1, 2, and 3. operand is that the other source operand is used as the result of the concatenation. The effect of specifying a null substring reference for both source operands is that the bytes of the receiver are specified for operands each set with a value of hex that a result is 40. The effect of specifying a null substring reference for the receiver not set regardless of the value of the source operands. is Exceptions Operands Exception 06 1 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation 44 partial damage 22 state system object damage X X X X X X X X Machine-dependent exception 03 machine storage 20 X Damage encountered 04 system object 1C Other Addressing limit exceeded X Machine support 02 machine check X 03 function check X Object access found X X X 02 object destroyed X X X 03 object suspended X X X 01 object not Chapter 2. Computation and Branching Instructions 2-46 Concatenate (CAT) Operands Exception 08 object compressed 24 1 does not Resource control limit 01 user profile storage limit 36 Other XXX XXX exist 02 pointer type invalid 2E 3 X Pointer specification 01 pointer 2 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-47 Convert Convert Op Code CVTBC BSC to Character (Hex) Extender BSC to Character (CVTBC) (CVTBC) Operand 1 Operand Operand 3 2 Operand [4-6] Receiver Controls Source Branch options Receiver Controls Source Branch targets Indicator Receiver Controls Source Indicator targets 10AF CVTBCB 1CAF CVTBCI 18AF options Operand 1: Operand 2: Character(3) variable scalar (fixed-length). Operand 3: Character scalar. Operand 4-6: Character variable scalar. • Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ILE access CVTBC ( var receiver receiverjlength var controls var source sourcejength var return code aggregate unsigned binary; aggregate aggregate; unsigned binary; signed binary ) The return_code will be set as follows: Return_Code Meaning -1 Completed Record. 0 Source Exhausted. 1 Truncated Record. Description: This instruction converts a string value from the BSC (binary synchronous communicompressed format to a character string. The operation converts the source (operand 3) from the BSC compressed format to character under control of the controls (operand 2) and places the cations) result into the receiver (operand 1). The source and receiver operands must both be character The controls operand must be strings. a character scalar that specifies additional information to be used to It must be at least 3 bytes in length and have the following format: control the conversion operation. • Controls operand — Source Char(3) offset Bin(2) Chapter 2. Computation and Branching Instructions 2-48 Convert — BSC to Character (CVTBC) Char(1) Record separator where bytes are to be accessed from the source operand. If the equal to or greater than the length specified for the source operand (it identifies a byte beyond the end of the source operand), a template value invalid (hex 3801) exception is signaled. As output from the instruction, the source offset is set to specify the offset that indicates how much of the The source offset specifies the offset source offset is source is processed when the instruction ends. The record separator converted records occur if , in specified with a value other than hex 01, contains the value used to separate the source operand. the converted records in Only the first 3 in A value of hex 01 specifies that record separators do not the source. bytes of the controls operand are used. Any excess bytes are ignored. The operation begins by accessing the bytes of the source operand located at the offset specified in is assumed to be the start of a record. The bytes of the record in the source the source offset. This into the receiver record operand are converted The strings to be built strings of consecutive The format » according to the following algorithm. in the receiver are contained nonblank characters. of the blank in compression entries occurring the source as blank compression entries and in the source are as follows: Blank compression entry Char(2) — Char(1) Interchange group separator — Count of Char(1) compressed blanks The interchange group separator has a fixed value of hex ID. compressed blanks provides for describing up to 63 compressed blanks. The count of the number of blanks (up to 63) to be decompressed is formed by subtracting hex 40 from the value of the count field. The count field can vary from a value of hex 41 to hex 7F. If the count field contains a The count of value outside of this range, a conversion (hex 0C01) exception is signaled. Strings of blanks described by blank compression entries in the source are repeated the number of times specified by the blank compression count. Nonblank strings in in the receiver the source are copied into the receiver intact with no alteration. is filled with converted data without encountering the end of the source operand, ends with a resultant condition of completed record. This can occur in two ways. If a the instruction record separator was not specified, the instruction ends when enough bytes have been converted from the source to fill the receiver. If a record separator was specified, the instruction ends when a source byte is encountered with that value prior to or just after filling the receiver record. The source offset value locates the byte following the last source record (including the record separator) for which conversion was completed. When the record separators/ alue is encountered, any remaining bytes in the If the receiver record receiver are padded with blanks. encountered (whether or not in conjunction with a record separator or the filling of the receiver), the instruction ends with a resultant condition of source exhausted. The source offset value locates the byte following the last byte of the source operand. The remaining bytes If in the end of the source operand is the receiver after the converted record are padded with blanks. the converted form of a record cannot be completely contained in the receiver, the instruction ends with a resultant condition of truncated record. The offset value for the source locates the byte folIf lowing the last source byte for which conversion was performed, unless Chapter 2. a blank compression entry Computation and Branching instructions 2-49 Convert BSC to Character (CVTBC) was being processed. In this case, the source offset is set to locate the byte after the blank comthe source does not contain record separators, this condition can only occur for the which a blank compression entry was being converted when the receiver record became full. pression entry. case in Any form If of overlap between the operands on this instruction yields unpredictable results in the receiver operand. Resultant Conditions • Completed record-The receiver record has been completely filled with converted data from a source record. • Source exhausted-AII of the bytes operand. • Truncated record-The receiver record cannot contain in the source operand have been converted into the receiver all of the converted data from the source record. Exceptions Operands Exception 06 1 Addressing 01 03 range 06 optimized addressability invalid Argument/parameter 01 0C parameter reference violation X Damage encountered 04 System object 44 1C Other Computation 01 conversion 10 3 XXX XXX XXX XXX XXX space addressing violation 02 boundary alignment violation 08 2 partial damage state X system object damage X Machine-dependent exception 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X Object access 01 object not XXX XXX XXX XXX XXX found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid Chapter 2. Computation and Branching Instructions 2-50 Convert BSC Character (CVTBC) to Operands 1 Exception 2C 2 3 X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 X exceeded XXX Scalar specification 01 scalar type invalid 36 Space management 01 38 Other Program execution X space extension/truncation Template specification X 01 template value invalid Chapter 2. Computation and Branching Instructions 2-51 Convert Character to Convert Character to Op Code CVTCB (Hex) BSC (CVTCB) BSC (CVTCB) Extender Operand 1 Operand Operand 2 3 Operand [4-5] Receiver Controls Source Branch options Receiver Controls Source Branch targets CVTCB Indicator Receiver Controls Source Indicator targets 188F options 108F CVTCBB 1C8F Operand 1: Operand 2: Character(3) variable scalar (fixed-length). Operand 3: Character scalar. Operand 4-5: Character variable scalar. • Branch Form - Branch number. • indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ILE access CVTCB ( var recei ver : receiver_length var controls var source sourcejength var return_code : : : : : aggregate ; unsigned binary, aggregate-, aggregate-, unsigned binary, signed binary ) The return_code will be set as follows: Return_Code Meaning -1 Receiver Overrun. 0 Source Exhausted. Description: This instruction converts a string value from character to BSC (binary synchronous communications) compressed format. The operation converts the source (operand 3) from character to the BSC compressed 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 controls operand must be a character scalar that specifies additional information to be used to control the conversion operation. It must be at least 3 bytes in length and have the following format: • Controls operand - Char(3) Receiver offset — Record Bin(2) separator Char(1) Chapter 2. Computation and Branching Instructions 2-52 Convert Character to BSC (CVTCB) to be placed into the receiver operand. If the for the receiver operand (it identifies a specified length the receiver offset is equal to or greater than (hex 3801) exception is signaled. As invalid value byte beyond the end of the receiver), a template the offset that indicates how much of the specify output from the instruction, the receiver offset is set to The receiver offset specifies the offset receiver has been when filled The record separator converted records in , where bytes are the instruction ends. separate specified with a value other than hex 01, contains the value used to are not separators record that specifies hex 01 the receiver operand. A value of if to be placed into the receiver to separate converted records. Only the first 3 bytes of the controls The source operand is assumed operand are used. Any excess bytes are ignored. to be converted into the receiver operand at the location specified in the source operand are the receiver offset according to the fol- of the record one record. The bytes in lowing algorithm. The bytes of consecutive blank (hex 40) of the source record are interrogated to identify the strings occur in the source record. Only characters and the strings of consecutive nonblank characters which of conversion into the purposes for string blank a as three or more blank characters are treated receiver. As the blank and nonblank strings are encountered in the source, they are packaged into the receiver. entries. The format of Blank strings are reflected in the receiver as one or more blank compression the blank compression entries built into the receiver are as follows: a Blank compression entry Char(2) - Interchange group separator Char(1) - Count of compressed blanks Char(1) The interchange group separator has a The count of fixed value of compressed blanks provides for compressing up formed by adding hex 40 to the actual number field can vary from a value of hex 43 to hex 7F. is Nonblank strings are copied hex ID. to 63 blanks. of blanks (up to 63) to be into the receiver intact with The value of the count compressed. The count field no alteration or additional control information. encountered, the record separator value if specified is placed into source exhausted. The receiver the receiver and the instruction ends with a resultant condition of receiver. The value of the remaining the record in offset value locates the byte following the converted bytes in the receiver after the converted record is unpredictable. When the end of the source record is receiver (including the record the converted form of a record cannot be completely contained in the overrun. The receiver receiver of condition separator if specified), the instruction ends with a resultant byte located by the the with starting offset remains unchanged. The remaining bytes in the receiver, If receiver offset, are unpredictable. Any form of overlap between the operands on this instruction yields unpredictable results in the receiver operand. Resultant Conditions » Source exhausted-AII of the bytes in the source operand have been converted into the receiver operand, • Receiver overrun-An overrun condition in the source operand were processed. in the receiver operand Chapter 2. was detected before all of the bytes Computation and Branching Instructions 2-53 Convert Character to BSC (CVTCB) Exceptions Operands Exception 06 01 08 space addressing violation 3 X X X X X X 03 range X X X 06 optimized addressability invalid X X X X X X parameter reference violation Damage encountered 44 partial damage state X system object damage X Machine-dependent exception 03 machine storage limit exceeded 20 X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found 02 object destroyed 03 object suspended X X X X X X X X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X X X Program execution 04 invalid branch target 2E Resource control X limit 01 user profile storage limit 32 exceeded X Scalar specification 01 scalar type invalid 36 X X X Space management 01 38 Other Argument/parameter 04 System object 1C 2 02 boundary alignment violation 01 10 1 Addressing space extension/truncation X Template specification 01 template value invalid X Chapter 2. Computation and Branching Instructions 2-54 Convert Character to Hex (CVTCH) Convert Character to Hex (CVTCH) Op Code Operand (Hex) Operand 2 Source 1 Receiver 1082 Operand 1 Operand 2: Character variable scalar. : Character variable scalar. to a Each character (8-bit value) of the string value in the source operand is converted relate must characters operand source The operand. (4-bit value) and placed in the receiver Description: hex digit to valid hex digits or a conversion (hex 0C01) exception Characters Hex Hex FO-hex F9 Hex 0-hex Hex Cl-hex C6 Hex A-hex is signaled. Digits 9 F right until all the hex The operation begins with the two operands left-adjusted and proceeds left to it is logically small, too is operand source the If filled. been digits of the receiver operand have a length conlarge, too is operand source the If (hex F0). padded on the right with zero characters signaled. is exception 2A0A) (hex formance (hex 0C08) or an invalid operand length length value of zero) may be Substring operand references that allow for a null substring reference (a for the source is that reference substring null a specifying effect of specified for operands 1 and 2. The a null substring specifying of effect The 00. hex of value the bytes of the receiver are each set with a reference for the receiver is that no result is set. Exceptions Operands Exception 06 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid X X X X X X X X X X parameter reference violation Computation X 01 conversion X 08 length conformance 10 44 partial damage system object damage Machine-dependent exception 03 machine storage 20 XXX XXX Damage encountered 04 system object 1C Other Argument/parameter 01 0C 2 Addressing 01 08 1 limit exceeded Machine support 02 machine check Chapter 2. Computation and Branching Instructions 2-55 Convert Character to Hex (CVTCH) Operands Exception 03 function check 22 1 2 X X X x X X X X X X Other Object access 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 36 exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-56 Convert Character to Convert Character to Op Code MRJE (CVTCM) Operand Extender (Hex) MRJE (CVTCM) 1 Operand Operand 2 Operand 3 [4-5] Receiver Controls Source Branch options Receiver Controls Source Branch targets CVTCMI Indicator Receiver Controls Source Indicator targets 188B options CVTCM 108B CVTCMB 1C8B Operand 1: Character variable scalar. Operand 2: Character(13) variable scalar (fixed-length). Operand 3: Character scalar. Operand 4-5\ • Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ILE access I i CVTCM ( var receiver receiverjength var controls var source sourcejength var return_code : aggregate-, : unsigned binary-, : aggregate-, : aggregate-, : : unsigned binary; signed binary ) The return_code will be set as follows ReturnCode Meaning -1 Receiver Overrun. B Source Exhausted. This instruction converts a string of characters to MRJE (MULTI-LEAVING remote job character to the MRJE entry) compressed format. The operation converts the source (operand 3) from compressed format under control of the controls (operand 2) and places the results in the receiver Description: (operand 1). The source and receiver operands must both be character specified as either a signed or unsigned immediate value. strings. The source operand cannot be The source operand can be described through the controls operand as being composed of one or more to be ignored fixed length data fields, which may be separated by fixed length gaps of characters of data to be amount during the conversion operation. Additionally, the controls operand specifies the processed from the source to produce a converted record value than the length of the data fields in the source. in the receiver. This may be The following diagram shows a different this structure for the source operand. Chapter 2. Computation and Branching Instructions 2-57 Convert Character to MRJE (CVTCM) Actual Source Operand Bytes data Sap field data field data flap field gap J Data Processed as Source Records record rec ord record record rec AACOXM) 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: • Controls operand — Char(13) Receiver offset Bin(2) — Source - Algorithm modifier Char(1) — Source record length Char(1) — Data — Gap - Gap - offset field Bin(2) length Bin(2) offset Bin(2) length Bin(2) Record control block (RCB) value Char(1) As input to the instruction, the source offset and iver 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 * Hex 00 = Perform • Hex = Perform only truncation of 01 full valid values: compression. trailing blanks. The source record length value specifies the amount of data from the source source record length of 0 The d ata is to be processed. specified, a template value invalid (hex 3801) exception is signaled. If a field length value specifies the length of the data fields in the source. Data fields occurring in 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 the source may be separated by gaps ignored. The g ap 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. tive to the value of source operand. The gap offset value is ignored if It is assumed the data field length is to be valid rela- specified with a 0. The g ap leng th value specifies the amount of data occurring between data fields in the source operand be ignored during the conversion operation. The gap length value is ignored if the data length is specified with a value of 0. which field is to Chapter 2. Computation and Branching Instructions 2*58 Convert Character to The record control block (RGB) value field specifies the RCB value form of each record in the receiver. It can have any value. Only the first 13 bytes of the controls that MRJE (CVTCM) to precede the converted is operand are used. Any excess bytes are ignored. The operation begins by accessing the bytes of the source the location specified by the Only the bytes of the data fields operand at in source offset. This is assumed to be the start of a source record. the causing ignored, are fields the source are accessed for conversion purposes. Gaps between data 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 converby the receiver sion operation. They are converted into the receiver operand at the location specified offset according to the following algorithm. The RCB value is placed into the An SRCB (sub record first byte of the receiver record. control byte) value of hex 80 is placed into the second byte of the receiver compression (a value of hex 00) then: record. If the algorithm modifier specifies full to locate the blank character strings (2 or The bytes of the source record are interrogated secutive blanks), identical character strings (3 character strings occurring in the source. tical record If is or more consecutive blank character string occurring at A more con- and nonidenthe end of the identical characters), treated as a special case (see following information on trailing blanks). 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 end of the source record. If one exists, it is treated as a string of trailing blanks. to it in the record are treated as one string of nonidentical characters. The strings encountered (blank, identical, or nonidentical) are reflected or more SCBs (string control bytes) in the receiver to describe them. The format • SCB The bit of the format SCBs o k is meanings 1 built into the receiver in string exists at the All characters prior the receiver by building one is: jjjjj are: Bit Value Meaning o 0 End of record; the EOR SCB 1 All 0 The string is 1 The string is not is hex 00. other SCBs. For k = compressed. compressed. 0: Blanks (hex 40s) have been deleted. Nonblank characters have been deleted. The next character specimen character. For k This JJJJJ Ijjjjj = the data stream is the 1 bit is part of the length field for length of have been deleted Number of characters that Number of characters to the next 1-63. in SCB uncompressed if k = 0. (no compression) The uncompressed (nonidentical bytes) Chapter 2. follow the data. The value can be if k SCB = in 1. 2-31. The value can be the data stream. Computation and Branching Instructions 2-59 Convert Character to When the end of a source record receiver. an EOR SRCB, is encountered, an EOR Trailing blanks in a record including a record of MRJE (CVTCM) SCB (hex 00) is built into the blanks are represented in the receiver by (end of record) all However, a record of all blanks is reflected in the compressed result by an RCB, an compression entry describing an 'unlike string' of one blank character, and an EOR character. character. a 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 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 with a resultant condition of receiver overrun. converted record Any form is unpredictable, of overlap between the operands of this instruction yields unpredictable results in the receiver operand. Resultant Conditions * Source exhausted-AII complete records receiver operand. Receiver overrun-An overrun condition in the source operand. in in the source operand have been converted into the the receiver operand was detected prior to processing all of the bytes 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. If Exceptions Operands Exception 06 1 2 3 space addressing violation X X X 02 boundary alignment violation X X X 03 range X X X 06 optimized addressability invalid X X X Other Addressing 01 Chapter 2. Computation and Branching Instructions 2-60 Convert Character to MRJE (CVTCM) Operands 1 Exception 08 10 3 parameter reference violation Damage encountered X 04 System object damage state 44 1C partial 22 X system object damage Machine-dependent exception 03 machine storage 20 limit X exceeded Machine support 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Other XXX Argument/parameter 01 2 Program execution 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 exceeded XXX Scalar specification 01 scalar type invalid 36 Space management 01 38 X space extension/truncation Template specification X 01 template value invalid Chapter 2. Computation and Branching Instructions 2-61 Convert Character to Numeric (CVTCN) Convert Character to Numeric (CVTCN) Op Code Operand (Hex) 1083 Operand 2 Source 1 Receiver Operand 3 Attributes Operand 1: Operand 2: Character scalar or data-pointer-defined character scalar. Operand 3: Character(7) scalar or data-pointer-defmed character scalar. Numeric variable scalar or data-pointer-defmed numeric scalar. The character scalar specified by operand 2 is treated as though it were a numeric scalar with the attributes specified by operand 3. The character string source operand is converted to the numeric forms of the receiver operand and moved to the receiver operand. The value of operand 2, when viewed in this manner, is converted to the type, length, and precision of the numeric receiver, operand 1, following the rules for the Copy Numeric Value instruction. Description: The length of operand is it 2 must be large enough to contain the numeric value described by operand not large enough, a scalar value invalid (hex 3203) exception is signaled. If it is larger than needed, 3. If leftmost bytes are used as the value, and the rightmost bytes are ignored. its Normal rules of arithmetic conversion apply except for the following. If operand 2 is interpreted as a zoned decimal value, a value of hex 40 in the rightmost byte referenced in the conversion is treated as a positive sign and a zero digit. a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled, the binary value if the decimal value contains 15 or fewer significant nonfrac- If contains the correct truncated result only tional digits. The format of the * attribute operand specified by operand 3 is as follows: Scalar attributes - Scalar type Hex Hex Hex Hex Hex - Char(7) Char(1) = Signed binary = 01 Floating-point 02 = Zoned decimal 03 = Packed decimal 0A = Unsigned binary 00 Scalar length binary: If - If Length (L) (where L = 2 or 4) Bits 0-15 = 4 or Bits 0-15 floating-point: - If Bin(2) Length (L) (where L 8) zoned decimal or packed decimal: - Fractional digits (F) - Total digits (T) (where - Reserved 1 < T < 31 Bits 0-7 Bjts 8 _ 15 and 0 <F< T) (binary 0) Bin(4) Exceptions Chapter 2. Computation and Branching Instructions 2-62 Convert Character to Numeric (CVTCN) 12 Operands Exception 06 space addressing violation 02 boundary alignment 03 range 04 external data object not found 06 optimized addressability invalid 08 Argument/parameter 01 0C parameter reference violation Computation X 02 decimal data 06 floating-point overflow X 07 floating-point underflow X 0A size X 0C floating-point conversion X 0D floating-point inexact result X Damage encountered 04 system object damage state 44 1C partial system object damage 22 limit X X X X X Machine support 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 03 object suspended 08 object compressed Pointer specification 01 pointer does not exist 02 pointer type invalid Resource control limit 01 user profile storage limit 32 X X 02 object destroyed 2E X exceeded 01 object not found 24 X Machine-dependent exception 03 machine storage 20 X X 09 floating-point invalid operand 10 Other XXX XXX XXX XXX XXX XXX Addressing 01 3 X exceeded Scalar specification X 01 scalar type invalid X X 02 scalar attribute invalid X 03 scalar value invalid X Chapter 2, Computation and Branching Instructions 2-63 Convert Character to Numeric (CVTCN) 12 Operands Exception 36 Space management 01 space extension/truncation 3 Other X Chapter 2. Computation and Branching Instructions 2-64 Convert Character to Convert Character to Op Code CVTCS SNA (CVTCS) Extender (Hex) SNA (CVTCS) Operand 1 Operand Operand 2 3 Operand [4-5] Receiver Controls Source Branch options Receiver Controls Source Branch targets Indicator Receiver Controls Source Indicator targets 10CB CVTCSB 1CCB CVTCSI 18CB options Operand 1: Character variable scalar. Operand 2: Character(15) variable scalar (fixed length). Operand 3: Character scalar. Operand 4-5 • Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ILE access CVTCS ( var receiver receiverjlength var controls var source : : : : sourcej ength var return code : : aggregate ; unsigned binary, aggregate ; aggregate ; unsigned binary, signed binary ) The return code will be set as follows: ReturnCode Meaning -1 Receiver Overrun. 0 Source Exhausted. Description: This instruction converts the source (operand architecture) format under control of the controls (operand (operand 3) 2) from character to SNA (systems network and places the result into the receiver 1). The source and receiver operands must both be character specified as an immediate operand. strings. The source operand may not be The source operand can be described by the controls operand as being one or more fixed-length data 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. fields that may be separated Chapter 2. Computation and Branching Instructions 2-65 Convert Character to SNA (CVTCS) Actual Source Operand Bytes Data Processed as Source Records record rac ord record record rec AAC 010-0 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: • Controls operand Char(15) - Receiver offset Bin(2) — Source Bin(2) — Algorithm modifier Char(1) — Source record length Char(1) - Data Bin(2) — Gap - Gap offset length field offset Bin(2) length Bin(2) — Record separator character Char(1) — Prime compression character Char(1) — Unconverted source record bytes Char(1) 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 are output from the instruction, they specify offsets that indicate how much of the operation is complete when the instruction ends. field 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 0 Meaning = Do not perform compression. 0 = I 1-2 Perform compression. = Do 00 not use record separators and no blank truncation. Do not perform data transparency conversion. 01 10 = Reserved. = Use record separators and perform blank truncation. Do not perform data transparency conversion. II 3 0 1 4-7 = Use record separators and perform blank truncation. = Do not perform = Perform record record spanning. spanning, (allowed only when bit 1 = Perform data transparency conversion. 1) (Reserved) Chapter 2. Computation and Branching Instructions 2-66 Convert Character to The source record length value produce a converted record in specifies the the receiver. amount SNA (CVTCS) of data from the source to be processed to Specification of a source record length of zero results in a template value invalid (hex 3801) exception. value specifies the length of the data fields in the source. Data fields occurring in 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 data field length the source The gap may gap offset value specifies the offset to the next output from the instruction. This is located by the source offset value. relative to the source operand. in No validation The gap offset done is value is This value the source. relative to the current byte to be processed for this offset. ignored if It is in is both input to and the source as assumed the data field length to be valid 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 zero. is The record separator character value record in the receiver. SNA The Convert blanks. It record separator value is specifies the character that precedes the converted form of each when the previous record is truncating trailing Character instruction recognizes any value that is less than hex 40. The ignored if record separators are not used as specified in the algorithm modi- also serves as a delimiter to fier. 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 record spanning function record bytes field is is specified in the algorithm modifier, the unconverted source both input to and output from the instruction. On input, a value of hex 00 means it That is, a record is the start of a new record and the initial nonzero value less than or separator character has not yet been placed in the receiver. On input, a 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 conversion step is yet to be performed. 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 record spanning function record bytes value Only the first is is not specified in the algorithm modifier, the unconverted source ignored. 15 bytes of the controls operand are used. Any excess bytes are ignored. is presented as a series of separately performed steps that allowable combinations to accomplish the conversion function. It is presented this to allow for describing these functions separately. However, in the actual execution of the instructhese functions may be performed in conjunction with one another or separately depending upon The description of the conversion process may be selected in which technique is way tion, determined to provide the best implementation. Chapter 2. Computation and Branching Instructions 2-67 Convert Character to SNA (CVTCS) 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 string processing is which case compression must be specified, The operation begins by accessing the bytes of the source operand source it indicates that to be performed. at the location specified by the offset. When record processing When the record spanning function has not been specified to locate the start of a record. is specified, the source offset may locate the start of a full or partial record. the algorithm modifier the source offset in , is assumed When the record spanning function has been specified in the algorithm modifier the source offset is 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 com, assumed pleting the conversion of the current source record before processing the next When string processing is full source record. 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 ends with a resultant condition of source exhausted. is encountered, the instruction 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 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. with a resultant condition of receiver overrun. 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. Chapter 2. Computation and Branching Instructions 2-68 Convert Character to SNA (CVTCS) The first function performed is trailing blank truncation. 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. conversion process for this record is completed by placing the truncated record into the If the truncated record cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. When the 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 If not, the receiver. When the receiver. operand is the record spanning function updated to describe only the last fully is not specified the receiver is unpredictable. The second function performed is data transparency conversion. ; remaining bytes performed if in the function is specified in in converted record the algorithm modifier the controls , in the receiver and the value of the Data transparency conversion the algorithm modifier. This provides for making the data is in a scanning for record record transparent to the Convert SNA 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 to Character instruction in the area of its . . 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 this record with the If not, is specified in the algorithm modifier, the conversion process continues for compression function. the conversion process for this record receiver. If is completed by placing the transparent record the transparent record cannot be completely contained in into the the receiver, the instruction ends with a resultant condition of receiver overrun. is specified in the algorithm modifier, as much of the transparent 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 When the record spanning function record as will fit is is not spanned out of the receiver. The remaining bytes of the transparent record, if any, 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 the record will these unused bytes is unpredictable. Chapter 2. Computation and Branching Instructions 2-69 Convert Character to SNA (CVTCS) When the 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 unpredictable. is The third function performed is compression. ; 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 The character the source. strings encountered (prime, duplicate SCB and nonduplicate) are reflected in the compressed Compression strings are compossibly followed by one or more bytes of data related to the more compression data by building one or prised of an in (string control byte) strings to describe them. character string to be described. The format of an SCB and the description of the data ” that may follow it are: SCB Char(1) - Bits 0-1 Control 00 = n nonduplicate characters are between SCB and this the next one; where n is the value of the count field (1-63). 01 10 = = Reserved This count 11 = SCB represents n deleted prime compression characters; where n The next byte is the next SCB. is the value of the field (2-63). SCB represents n deleted duplicate characters; where n is the value of the count The next byte contains a specimen of the deleted characters. The byte following the specimen character contains the next SCB, This field (3-63). - Count Bits 2-7 number This contains the or the number of characters that have been deleted for a prime or duplicate string, SCB for a nonduplicate string. A count value of zero of characters to the next cannot be produced. When record processing is The compression function specified, the compression performed on is performed as follows. just the converted form of the current source record 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. is including the record separator character. The converted form The conversion process for this record is completed by placing the compressed record receiver. If the compressed record cannot be completely contained in the receiver, the ends with a resultant condition of receiver overrun. When into the instruction the record spanning function is specified in the algorithm modifier, as much of the compressed 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 record as will fit is 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 Chapter 2. Computation and Branching Instructions 2-70 Convert Character to SNA (CVTCS) is specified, the transparent data being described 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 non- special case where data transparency conversion not spanned out of the receiver. This is duplicate string containing the record separator and the some entry for TRN control, and up to a 2-byte compression of the transparent data, the nonduplicate compression entry is adjusted to describe only 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 record separator. the appropriate TRN control information when performing transparency conversion. the 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 When , the receiver bytes in When string processing The compression string basis. is unpredictable. is function In this specified, the is for the in is performed as follows. source operand on a compression the controls operand related to record processing are ignored. performed on the data case, the fields The conversion process compression source operand is for the entire completed by placing the compressed data into the receiver. 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 When the 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 if remain When in the receiver. the compressed data can be completely contained resultant condition of source exhausted. trols operand is updated to indicate that in the receiver, the instruction ends with a The compressed data all of the source data is placed into the receiver and the con- 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 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 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. Chapter 2. Computation and Branching Instructions 2-71 Convert Character to Limitations: Any form The following are limits that SNA (CVTCS) apply to the functions performed by this instruction. of overlap between the operands on this instruction yields unpredictable results in the receiver operand. Substring operand references that allow for a null substring reference (a length value of zero) be specified may not for this instruction. Resultant Conditions • • Source exhausted operand. Receiver overrun bytes in - - All bytes in the source operand have been converted into the receiver An overrun condition in the receiver operand was detected before were processed. all of the the source operand 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. it In this case, the user of the instruction must move this partial record to combine in the source operand to provide for its being processed correctly with the rest of the record upon the next invocation of the instruction. If full records are provided, the instruction performs conversions out to the end of the source operand and no special processing is required. its For the special case of a tie source exhausted condition between the source exhausted and receiver overrun conditions, the recognized first. That is, when source exhausted is the resultant is may also be full. In this case, the receive 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 condition, the receiver same When the receiver overrun condition always contain data that can be converted. controls operand template. the source will is the resultant condition, Exceptions Operands Exception 06 1 2 3 Spacing addressing violation X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X 01 08 Argument/parameter 01 10 Other Addressing Parameter reference violation Damage encountered 04 System object damage state 44 1C Partial system object damage Machine-dependent exception 03 Machine storage 20 limit exceeded Machine support 02 Machine check Chapter 2. Computation and Branching Instructions 2-72 Convert Character to SNA (CVTCS) Operands Exception 03 Function check 22 1 2 3 X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C X X X X X X Program execution X 04 Invalid branch target 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification 01 36 X Scalar type invalid X X Space management X 01 space extension/truncation 38 Other Template specification 01 Template value X invalid Chapter 2. Computation and Branching Instructions 2-73 Convert Decimal Form to Floating-Point (CVTDFFP) Convert Decimal Form to Floating-Point (CVTDFFP) Op Code Operand (Hex) 107F Operand 1 Receiver Operand 2 3 Decimal Decimal exponent significand Operand 1: Operand 2: Packed scalar or zoned scalar. Operand 3: Packed scalar or zoned Floating-point variable scalar. scalar. Description: This instruction converts the decimal form of a floating-point value specified by a decimal exponent and a decimal significand to binary floating-point format, and places the result in the receiver operand. The decimal exponent (operand 2) and decimal significand (operand 3) are considered to specify a decimal form of a floating-point number. The value of this number is considered to be as follows: Value = S * (10**E) where: S E = = * ** The value of the decimal significand operand. The value of the decimal exponent operand. Denotes multiplication. Denotes exponentiation. The decimal exponent must be specified as a decimal integer value; no fractional digit positions may be specified in its definition. The decimal exponent is a signed integer value specifying a power of 10 which gives the floating-point value its magnitude. A decimal exponent value too large or too small to be represented in the receiver will result in the signaling of the appropriate floating-point overflow (hex 0C06) or floating-point underflow (hex 0C07) exception. The decimal must be specified as a decimal value with a single integer digit position and The decimal significand is a signed decimal value specifying decimal digits which give the floating-point value its precision. The significant digits of the decimal significand are considered to start with the leftmost nonzero decimal digit and continue to the right to the end of the decimal significand value. Significant digits beyond 7 for a short float receiver, and beyond 15 for a long float receiver exceed the precision provided for in the binary floating-point receiver. These excess digits do participate in the conversion to provide for uniqueness of the conversignificand optional fractional digit positions. sion as well as for proper rounding. The decimal form ands is converted floating-point value specified by the decimal to a binary floating-point exponent and decimal significand oper- number and rounded to the precision of the result field as follows: Source values which, (10**31-1) *10** + 31 in magnitude M, are in the range where (10**31-1) * 10**-31 <= M <= are converted subject to the normal rounding error defined for the floating-point rounding modes. in magnitude M, are in the range where (10**31-1) * 10**-31 > M > (10**31-1) are converted such that the rounding error incurred on the conversion may exceed that defined above. For round to nearest, this error will not exceed by more than .47 units in the least Source values which, *10** + 31 significant digit position of the result in relation to the error that would be incurred for normal will not exceed 1.47 units in the For the other floating-point rounding modes, this error significant digit position of the result. rounding. The converted and rounded value is least then assigned to the floating-point receiver. Chapter 2. Computation and Branching Instructions 2-74 Convert Decimal Form to Floating-Point (CVTDFFP) Exceptions Operands Exception 06 1 Spacing addressing violation 02 Boundary alignment violation 03 Range 06 Optimized addressability invalid 08 Argument/parameter 01 0C Parameter reference violation X 06 Floating-point overflow X 07 Floating-point underflow X 0D X Floating-point inexact result 44 damage Partial 22 X state X system object damage Machine-dependent exception 03 Machine storage 20 limit X exceeded Machine support 02 Machine check X 02 Function check X XXX XXX XXX XXX XXX Object access 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 32 exceeded X XXX Scalar specification 01 36 X Damage encountered 04 System object 1C Other Computation 02 Decimal data 10 3 XXX XXX XXX XXX XXX Addressing 01 2 Scalar type invalid Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-75 Convert External Form to Numeric Value (CVTEFN) Convert External Form to Numeric Value (CVTEFN) Op Code Operand (Hex) 1087 Operand 1 Receiver Operand Mask 2 Source Operand /: Operand 2: Character scalar or data-pointer-defined character scalar. Operand 3: Character(3) scalar, CVTEFN var var var var var Numeric variable scalar or data-pointer-defined numeric null, 3 scalar. or data-pointer-defined character(3) scalar. ( receiver receiver_attributes source sourcej ength mask any numeric type; aggregate ; aggregate ; unsigned binary, aggregate ) This instruction scans a character string for a valid decimal Description: removes the display character, and places the by scanning the character string value in in number the source operand to make sure it in display format, The operation begins the receiver operand. is a valid decimal number display format. The character • in results string defined by Currency symbol The valid symbol - operand This value is is 2 consists of the following optional entries: optional and, determined by operand 3. present, must precede any sign and digit values. The currency symbol may be preceded in the field if by blank (hex 40) characters. • Sign symbol or may - This value is optional and, if present, follow the digit values (a trailing sign). may precede any digit values (a leading sign) Valid signs are positive (hex 4E) and negative (hex The sign symbol, if it is a leading sign, may be preceded by blank characters. If the sign symbol is a trailing sign, it must be the rightmost character in the field. Only one sign symbol 60). is allowed. • Decimal digits - Up to 31 decimal digits may be specified. Valid decimal digits are in the range of hex F0 through hex F9 (0-9). The first decimal digit may be preceded by blank characters (hex 40), but hex 40 values located to the right of the leftmost decimal digit are invalid. The decimal digits may be divided into two parts by the decimal point symbol: an integer part and a decimal point are interpreted as integer values. Digits to the right are interpreted as a fractional values. If no decimal point symbol is included, the value is interpreted as an integer value. The valid decimal point symbol is determined by operand 3. If the decimal point symbol precedes the leftmost decimal digit, the digit value is interpreted as a fractional value, and the leftmost decimal digit must be adjacent to the decimal point symbol. If the decimal point follows the rightmost decimal digit, the digit value is interpreted as an integer value, and the rightmost decimal digit must be adjacent to the decimal point. fractional part. Digits to the left of the Decimal digits in the integer portion may optionally have comma symbols separating groups of three digits. The leftmost group may contain one, two, or three decimal digits, and each succeeding group must be preceded by the comma symbol and contain three digits. The comma symbol must be adjacent to a decimal digit on either side. The valid comma symbol is determined by operand 3. Chapter 2. Computation and Branching Instructions 2-76 Convert External Form to Numeric Value (CVTEFN) Decimal digits in the fractional portion may not be separated by commas and must be adjacent to one another. Examples of external formats follow. The following symbols are used. currency symbol decimal point $ , comma D digit (hex F0-F9) blank (hex 40) + positive sign negative sign Comments Format $ + DDDD.DD Currency symbol, leading DD.DDD- Comma -.DDD No integer, leading sign $DDD,DDD- No fraction, + DD.DD $ sign, no comma separators symbol, no fraction, trailing sign comma Embedded blanks symbol, trailing sign before digits 3 must be a 3-byte character scalar. Byte 1 of the string indicates the byte value that is to be used for the currency symbol. Byte 2 of the string indicates the byte value to be used for the comma symbol. Byte 3 of the string indicates the byte value to be used for the decimal point symbol. If operand 3 is null, the currency symbol (hex 5B), comma (hex 6B), and decimal point (hex 4B) are used. Operand If the syntax rules are violated, a conversion (hex 0C01) exception is signaled. If not, a formed from the digits of the display format character string. This number receiver operand following the rules of a normal arithmetic conversion. value is is zoned decimal placed in the If a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. Exceptions Operands Exception 06 1 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X Addressing 01 08 Spacing addressing violation Argument/parameter 01 OC Parameter reference violation Computation 01 X Conversion X 0A Size 10 Other Damage encountered 04 System object damage 44 Partial system object damage Chapter 2. X X X X X X X X Computation and Branching Instructions 2-77 Convert External Form Numeric Value (CVTEFN) to Operands Exception 1C 1 03 Machine storage 20 22 2 3 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X exceeded X Scalar specification 01 X Scalar type invalid 02 Scalar attribute invalid 36 X limit 01 user profile storage limit 32 Other Machine-dependent exception X X X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-78 Convert Floating-Point to Decimal Form (CVTFPDF) Convert Floating-Point to Decimal Form (CVTFPDF) Op Code (Hex) CVTFPDF Operand Operand 1 Decimal exponent 10BF Operand 2 3 Source Decimal significand CVTFPDFR Decimal exponent 12BF Source Decimal significand Operand /: Packed variable scalar or zoned variable scalar. Operand 2: Packed variable scalar or zoned variable scalar. Operand 3: Floating-point scalar. This instruction converts a binary floating-point value to a decimal form of a floating-point value specified by a decimal exponent and a decimal significand, and places the result in the decimal exponent and decimal significand operands. Description: The value of this Value = S * number is considered to be as follows: (10**E) where: S = The value of the decimal significand operand. E = The value of the decimal exponent operand. * Denotes multiplication. ** Denotes exponentiation. The decimal exponent must be specified as a decimal integer value. No fractional digit positions are allowed. must be specified with at least five digit positions. The decimal exponent provides for containing a signed integer value specifying a power of 10 which gives the floating-point value its magIt nitude. The decimal significand must be specified as a decimal value with a single integer digit position and The decimal significand provides for containing a signed decimal value specifying decimal digit is which give the floating-point value its precision. The decimal significand is formed as a normalized value, that is, the leftmost digit position is nonzero for a nonzero optional fractional digit positions. source value. When the source contains a representation of a normalized binary floating-point number with decimal beyond the leftmost 7 digits for a short floating-point source or beyond the leftmost 15 significand digits digits for a long floating-point source, the precision allowed for the binary floating-point source is exceeded. When the source contains a representation of a denormalized binary floating-point number, it may provide less precision than the precision of a normalized binary floating-point number, depending on the particular source value. Decimal significand digits exceeding the precision of the source are set as a result of the conversion to provide for uniqueness of conversion and are correct, except for rounding errors. value. These digits are only as precise as the floating-point calculations that produced the source The floating-point inexact result (hex 0C0D) exception provides a means of detecting loss of precision floating-point calculations. in The binary floating-point source is converted to a decimal form floating-point value and rounded to the precision of the decimal significand operand as follows: Chapter 2. Computation and Branching Instructions 2-79 Convert Floating-Point • The decimal significand is Decimal Form (CVTFPDF) to formed as a normalized value and the decimal exponent is set accordingly. • For the nonround form of the instruction, the value to be assigned to the decimal significand is adjusted to the precision of the decimal significand, if necessary, according to the current float rounding mode in effect for the process. For the optional round form of the instruction, the decimal round algorithm is used for the precision adjustment of the decimal significand. The decimal round algorithm overrides the current floating-point rounding mode that is in effect for the process. • Source values which, (10**31-1) * 10** point rounding • + 31 in magnitude M, are in the range where (10**31-1) * 10**-31 <= M <= are converted subject to the normal rounding error defined for the floatingthe optional round form of the instruction. modes and Source values which, in magnitude M, are in the range where (10**31-1) * 10**-31 > M > (10**31-1) are converted such that the rounding error incurred on the conversion may exceed that defined above. For round to nearest and the optional round form of the instruction, this error will * 10** + 31 not exceed by more than .47 units in the least significant digit position of the result, the error that would be incurred for a correctly rounded result. For the other floating-point rounding modes, this error will not exceed 1.47 units in the least significant digit position of the result. necessary, the decimal exponent value • If • The converted and rounded value is is adjusted to compensate for rounding. then assigned to the decimal exponent and decimal significand operands, A size (hex 0C0A) exception cannot occur on the assignment of the decimal exponent or the decimal significand values. Limitations: The The following are result of the operation is limits that apply to the functions performed by this instruction. unpredictable for any type of overlap between the decimal exponent and decimal significand operands. Exceptions Operands Exception 06 1 Addressing 01 03 Range 06 Optimized addressability invalid Argument/parameter 01 0C 10 Parameter reference violation Other Computation 0C Invalid floating-point conversion 0D Floating-point inexact result X X X Damage encountered 04 System object 44 1C 3 XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment violation 08 2 Partial damage state X system object damage X Machine-dependent exception 03 Machine storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-80 Convert Floating-Point to Decimal Form (CVTFPDF) Operands Exception 20 22 1 2 3 02 Machine check X 03 Function check X Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X exceeded Scalar specification X 04 Scalar type invalid 36 X limit 01 user profile storage limit 32 Other Machine support X X Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-81 Convert Hex to Character (CVTHC) Convert Hex to Character (CVTHC) Op Code Operand (Hex) 1086 Operand Source 1 Receiver Operand 1: Character variable scalar. Operand 2: Character variable scalar. Description: character 2 Each hex digit (4-bit value) of the string value value) and placed in the receiver operand. in the source operand is converted to a (8-bit Hex Digits Hex 0-9 = Hex F0-F9 Hex A-F = Hex C1-C6 Characters The operation begins with the two operands left-adjusted and proceeds left to right until all the characoperand have been filled. If the source operand contains fewer hex digits than needed to fill the receiver, the excess characters are assigned a value of hex F0. If the source operand is too large, a length conformance (hex 0C08) or an invalid operand length (hex 2A0A) excep- ters of the receiver tion is signaled. Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that the bytes of the receiver are each set with a value of hex F0. The effect of specifying a null substring reference for the receiver is that no result is set. Exceptions Operands Exception 06 Spacing addressing violation X X 02 Boundary alignment X X 03 Range X X 06 Optimized addressability invalid X X X X Parameter reference violation Computation 08 Length conformance 10 X Damage encountered 04 System object damage state 44 1C Partial system object damage X X X X X X Machine-dependent exception 03 Machine storage limit exceeded 20 Other Argument/parameter 01 OC 2 Addressing 01 08 1 X Machine support 02 Machine check X 02 Function check X Chapter 2. Computation and Branching Instructions 2-82 Convert Hex to Character (CVTHC) Operands 1 2 Object not found X X 02 Object destroyed X X 03 Object suspended X X X X X X Exception 22 Object access 01 Other 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-83 Convert Convert Op Code MRJE (Hex) to MRJE to Character (CVTMC) Character (CVTMC) Extender Operand CVTMC 1 Operand Operand 2 Operand 3 [4-5] Receiver Controls Source Branch options Receiver Controls Source Branch targets CVTMCI Indicator Receiver Controls Source Indicator targets 18AB options 10AB CVTMCB 1CAB _ Operand 1: Character variable scalar. Operand 2: Character(6) variable scalar (fixed-length). Operand 3: Character scalar. Operand 4-5 Branch Form - Branch number. Indicator * point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ILE access CVTMC ( var receiver : aggregate unsigned binary, aggregate aggregate unsigned binary, signed binary ; receiver_length var controls var source source Jength var return code : : ; : ; : : ) The return_code will be set as follows: Return_Code Meaning -1 Receiver Overrun. 0 Source Exhausted. Description: This instruction converts a character string from the MRJE (MULTI-LEAVING remote job to character format. The operation converts the source (operand from the compressed format MRJE compressed format entry) results in 3) to character format the receiver (operand under control of the controls (operand 2) and places the 1). The source and receiver operands must both be character specified as either a signed or unsigned immediate value. strings. The source operand cannot be 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 6 bytes in length and have the following format: • Controls operand — Char(6) Receiver offset - Source Bin(2) offset Bin(2) Chapter 2. Computation and Branching Instructions 2-84 Convert As MRJE to Character (CVTMC) — Algorithm modifier Char(1) — Receiver record length Char(1) specify the offsets where bytes of input to the instruction, the source offset and receiver offset fields equal to or greater than the is offset If an processed. be to are and receiver operands the source beyond the end of the operand), a length specified for the operand it corresponds to (it identifies a byte the instruction, the source from output As signaled. template value invalid (hex 3801) exception is the operation is complete of much how offset and receiver offset fields specify offsets that indicate when the instruction ends. The algorithm modifier has the following » Hex 00 = Do . Hex = Move SRCBs 01 not move SRCBs valid values: (sub record control bytes) from the source into the receiver. from the source into the receiver. specifies the record length to be used to convert source records into the receiver record and does not the receiver operand. This length applies to only the string portion of specified, a template value invalid include the optional SRCB field. If a receiver record length of 0 is (hex 3801) exception is signaled. The receiver record length value Only the first 6 bytes of the controls operand are used, Any excess bytes are ignored. specified by the The operation begins by accessing the bytes of the source operand at the location records in the source the of bytes source offset. This is assumed to be the start of a record. The offset receiver the by specified operand are converted into the receiver operand at the location according to the following algorithm. The first byte of the source record considered to be an is RCB (record control byte) that is to be ignored during conversion. considered to be an SRCB. If an algorithm modifier of value ignored. If an algorithm modifier of value hex 01 was specified, the The second byte of the source record hex 00 was specified, the SRCB is SRCB is copied into the receiver. The strings more SCBs to be built in k The 1 the receiver record are described in the source after the SRCB by one or (string control bytes). The format of the SCBs o is in the source are as follows: jjjjj bit meanings are: Bit Value Meaning o 0 End of record;the 1 All 1 is hex 00. other SCBs. compressed. The string is The string is not = For k 0 EOR SCB compressed. 0: Blanks (hex 40s) have been deleted. Nonblank characters have been deleted. The next character in the data stream is the specimen character. For k This = 1: bit is part of the length field for length of uncompressed data. Chapter 2. Computation and Branching Instructions 2-85 Convert Bit Value MRJE Character (CVTMC) to Meaning Number of characters that have been deleted value can be 1-31. jjjjj Number Ijjjjj of characters to the next k=1. The value can be SCB if k = 0. The (no compression) if 1-63. The uncompressed (nonidentical bytes) follow the SCB in the data stream. A length of 0 encountered in an SCB results in the signaling of a conversion (hex 0C01) exception. Strings of blanks or nonblank identical characters described in the source record are repeated receiver the number of times indicated by the SCB count value. Strings of nonidentical characters described length indicated by the SCB count value. When an EOR (end of record) SCB (hex 00) blanks out to the end of the current record. in is the source record are encountered in moved the in into the receiver for the the source, the receiver is padded with the converted form of a source record is larger than the receiver record length, the instruction terminated by signaling a length conformance (hex 0C08) exception. If is 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 source), the instruction ends with a resultant condition of source exhausted. The receiver offset locates the byte following the last fully converted record in the receiver. The source offset locates the byte following the last source record for which conversion is complete. The value of the remaining bytes in the receiver after the last converted record are unpredictable. EOR SCB in 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 receiver offsert locates the byte following the last fully converted record in the receiver. The source offset locates the byte following the last source record for which conversion is complete. The value of the remaining bytes converted record is unpredictable. in the receiver after the last the source exhausted and the receiver overrun conditions occur at the same time, the source exhausted condition is recognized first. In this case, the receiver offset may contain a value equal to the length specified for the receiver which causes an exception to be signaled on the next invocation of the instruction. The processing performed for the source exhausted condition provides for this case if 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. If Limitations: Any form The following are of overlap limits that apply to the functions performed by this instruction. between the operands on receiver operand. this instruction yields unpredictable results in the Resultant Conditions Source exhausted operand. ’ Receiver overrun all of the bytes in - All full records in the source operand have been converted into the receiver An overrun condition the source operand. - in the receiver operand Chapter 2. was detected prior to processing Computation and Branching Instructions 2-86 Convert MRJE to Character (CVTMC) Exceptions Operands 06 2 3 X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X Addressing 01 08 Spacing addressing violation Argument/parameter 01 OC Parameter reference violation Computation 01 X Conversion X 08 Length conformance 10 Damage encountered 04 System object 44 1C Partial damage X state X system object damage Machine-dependent exception 03 Machine storage 20 Other 1 Exception limit X exceeded Machine support X 02 Machine check X 03 Function check 22 Object access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X 01 X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C X X X X X X Program execution X 04 Invalid branch target 2E Resource control limit 01 user profile storage limit 32 Scalar specification 01 36 X Scalar type invalid X X Space management 01 38 X exceeded X space extension/truncation Template specification 01 Template value X invalid Chapter 2. Computation and Branching Instructions 2-87 Convert Numeric to Character (CVTNC) Convert Numeric to Character (CVTNC) Op Code (Hex) Operand 10A3 Operand Source 1 Receiver Operand 2 3 Attributes Operand 1: Operand 2: Numeric scalar or data-pointer-defined numeric Operand 3: Character(7) scalar or data-pointer-defined character(7) scalar. Character variable scalar or data-pointer-defined character scalar. scalar. The source numeric value (operand 2) is converted and copied to the receiver character (operand 1). The receiver operand is treated as though it had the attributes supplied by operand °P erand 1. when viewed in this manner, receives the numeric value Description: string 3 ' of Copy Numeric Value rules of the The format of operand 3 as follows: is Scalar attributes • - Char(7) Scalar type Char(1) = Signed binary 01 = Floating-point 02 = Zoned decimal 03 = Packed decimal 0A = Unsigned binary Hex Hex Hex Hex Hex - 00 Scalar length - Length (L) (where L = 2 or 4) Bits 0-15 floating-point: If - Length (where L = 4 or 8) Bits 0-15 zoned decimal or packed decimal: - - Fractional digits (F) Bits 0-7 Total digits (T) < T < Reserved (binary 0) (where — Bin(2) binary: If If operand 2 following the instruction. 1 Bits 8-15 31 and O < F < T) Bin(4) The byte length of operand 1 must be large enough to contain the numeric value described by operand not large enough, a scalar value invalid (hex 3203) exception is signaled. If it is larger than needed, the numeric value is placed in the leftmost bytes and the unneeded rightmost bytes are unchanged by the instruction. 3. If it is If a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfrac- T I On Q n n I I i to Exceptions 12 Operands Exception 06 3 Other Addressing Chapter 2. Computation and Branching Instructions 2-88 Convert Numeric to Character (CVTNC) Operands 2 3 X X 02 Boundary alignment X X X 03 Range X X X 04 External data object not found X X X 06 Optimized addressability invalid X X X X X X 01 08 Spacing addressing violation Argument/parameter 01 OC Parameter reference violation Computation X 02 Decimal data 06 Floating-point overflow X 07 Floating-point underflow X X 09 Floating-point invalid operand X 0A Size 10 0C Invalid floating-point conversion X 0D Floating-point inexact result X Damage encountered 04 System object 44 1C Partial damage 22 state system object damage X X X X X X X X Machine-dependent exception 03 Machine storage 20 Other 1 X Exception limit X exceeded Machine support 02 Machine check X 03 Function check X Object access X X X 02 Object destroyed X X X 03 Object suspended X X X X X X X X X 01 Object not found 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification 01 X Scalar type invalid X X 02 Scalar attribute invalid X 03 Scalar value invalid 36 Space management 01 X space extension/truncation Chapter 2, Computation and Branching Instructions 2-89 Convert Convert Op Code CVTSC SNA to (Hex) Operand 1 Operand Operand 2 [4-6] Source Branch options Receiver Controls Source Branch targets Indicator Receiver Controls Source Indicator targets options Operand 1\ Operand 2: Character(14) variable scalar (fixed length). Operand 3: Character scalar. Operand 4-6: Character variable scalar. Branch Form - Branch number. Indicator CVTSC Operand 3 Controls 1CDB • (CVTSC) Receiver 10DB CVTSCI 18DB to Character Character (CVTSC) Extender CVTSCB SNA point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. ( var receiver aggregate ; unsigned binary, receiverjength var controls var source aggregate-, aggregate-, sourcejength unsigned binary-, signed binary var return_code ) The return code will be set as fol lows: Return_Code Meaning -1 Receiver Overrun. 0 Source Exhausted. 1 Escape Code Encountered Description: to character. This instruction converts a string value from The operation converts the source (operand control of the controls (operand 2) and places the SNA 3) (systems network architecture) format from SNA format to character under result into the receiver (operand The source and receiver operands must both be character strings. 1). The source operand may not be specified as an immediate operand. The controls operand must be a character scalar that specifies additional information to be used to control the conversion operation. It must be at least 14 bytes in length and have the following format: • Controls operand base template - Char(14) Receiver offset Bin(2) Chapter 2. Computation and Branching Instructions 2-90 Convert to Character — Source — Algorithm modifier Char(1) — Receiver record length Char(1) Char{1) separator — Prime compression Char(1) — Unconverted receiver record bytes Char(1) — Conversion status Char(2) — Unconverted transparency string bytes Char(1) — Offset into template to translate table Bin{2) Controls operand optional template extension Char(64) — Record Char(64) Upon (CVTSC) Bin(2) offset — Record • SNA separator translate table input to the instruction, the source offset and receiver offset fields specify the offsets where bytes equal to or greater than the of the source and receiver operands are to be processed. If an offset the end of the operand), a beyond specified for the operand it corresponds to (it identifies a byte is length the source template value invalid (hex 3801) exception is signaled. As output from the instruction, is complete operation the offset and receiver offset are set to specify offsets that indicate how much of when the instruction ends. The algorithm modifier specifies the optional functions to be performed. Any combination of functions the functions must be not precluded by the bit definitions below is valid except that at least one of algorithm modifier bits cannot be zero. Specification of an invalid algorithm modifier the algorithm value results in a template value invalid (hex 3801) exception. The meaning of the bits in specified. All modifier the following: is Bits Meaning 0 o 1_2 00 I = Do not perform decompression. Interpret a source character value of hex 00 as null. = Perform decompression. Interpret a source character value of hex 00 as a record separator. = No record separators in source, no blank padding. Do not perform data transparency conversion. 10 = Reserved. = Record separators I = Record 01 not perform data transparency conver- in source, perform blank padding. Do in source, perform blank padding. Perform data transparency conversion. sion. 3-4 00 01 10 11 5-7 separators = Do not put record separators into receiver. = Move record separators from source to receiver (allowed only when bit 1=1) = Translate record separators from source to receiver (allowed only when bit 1 =1) = Move record separator from controls to receiver. Reserved specifies the record length to be used to convert source records into record and does not the receiver operand. This length applies only to the data portion of the receiver zero results in a length of record receiver include the optional record separator. Specification of a if no record ignored is value length template value invalid (hex 3801) exception. The receiver record The receiver record length value separator processing is requested in the algorithm modifier. record The record separator value specifies the character that is to precede the converted form of each the only for used is operand controls the in the receiver. The record separator character specified in algorithm the specified in is function case where the move record separator from controls to receiver modifier or where a missing record separator in the source is detected. Chapter 2. Computation and Branching Instructions 2-91 Convert SNA to Character (CVTSC) The prime compression value specifies the character to be used as the prime compression character when performing decompression of the SNA format source data to character. It may have any value. The prime compression value is ignored if the perform decompression function is not specified in the algorithm modifier. The unconverted rec eiver record bytes value specifies the number of bytes remaining the current in receiver record that are yet to be set with converted bytes from the source. When record separator processing is specified in the algorithm modifier, this value is both input to and output from the instruction. On input, a value of hex 00 means it is the start of processing for a new record, and the initial conversion step is yet to be performed. This indicates that for the case where a function for putting record separators into the receiver is specified in the algorithm modifier, a record separator character has yet to be placed in the receiver. On input, a nonzero value less than or equal to the receiver record length specifies the number of bytes remaining in the current receiver record that are yet to be set with converted bytes from the source. This value is assumed to be the valid count of unconverted receiver record bytes relative to the current byte to be processed in the receiver as located by the receiver offset field. As such, it is used to determine the location of the next record boundary in the receiver operand. This value must be less than or equal to the receiver record length value; otherwise, a template value invalid {hex 3801) exception is signaled. On output, this field is set with a value as defined above which describes the number of bytes of the current receiver record not yet containing converted data. When record separator processing conversion status meaning of the Bits bits in field specifies 0 1 not specified in the algorithm modifier, this value ignored. is status information for the operation to be performed. is the following: The the conversion status Meaning = No transparency 0 is = Transparency string active. string active. Unconverted transparency string bytes value contains the remaining string length. 1-15 Reserved This field is both input to and output from the instruction. status over successive executions of the instruction. It provides for checkpointing the conversion If the conversion status indicates transparency string active, but the algorithm modifier does not specify perform data transparency conversion, a template value invalid (hex 3801) exception is signaled. The unconverted trans parency string bytes field specifies the number of bytes remaining to be converted for a partially processed transparency string in the source. When perform data transparency conversion is specified in the algorithm modifier, the unconverted transparency string bytes field can be both input to and output from the instruction. On is input, when the no transparency string active status is specified in the conversion status this value ignored. On input, when transparency string active status is specified in the conversion status, this value contains a count for the remaining bytes to be converted for a transparency string in the source. A value of hex 00 means the count field for a transparency string is the first byte of data to be processed from the source operand. A value of hex 01 through hex FF specifies the count of the remaining bytes to be converted for a transparency string. This value is assumed to be the valid count of unconverted transparency string bytes relative to the current byte to be processed in the source as located by the source offset field. Chapter 2. Computation and Branching Instructions 2-92 Convert SNA to Character (CVTSC) necessary along with the transparency string active status to describe a partially converted transparency string. A value of hex 00 will be set if the count field is the next byte to be processed for a transparency string. A value of hex 01 through hex FF specifying the number of remaining bytes to be converted for a transparency string, will be set if the count field has already On output, this value is set if been processed. not perform data transparency conversion verted transparency string bytes value is ignored. When do is specified the algorithm modifier the uncon- in , offset into template to translate table value specifies the offset from the beginning of the template to the record separator translate table. This value is ignored unless the translate record separators The from source to receiver function is specified in the algorithm modifier. The record separator translate table value specifies the translate table to be used in translating record separators specified in the source to the record separator value to be placed into the receiver. It is assumed to be 64 bytes in length, providing for translation of record separator values of from hex 00 to hex 3F. This translate table is used only when the translate record separators from source to receiver function is specified in the algorithm modifier. See the record separator conversion function under the conversion process described below for more detail on the usage of the translate table. first 14 bytes of the controls operand base template and the optional 64-byte extension area specified for the record separator translate table are used. Any excess bytes are ignored. Only the is presented as a series of separately performed steps, which may be selected in allowable combinations to accomplish the conversion function. It is presented this way to allow for describing these functions separately. However, in the actual execution of the instruction, these functions may be performed in conjunction with one another or separately, depending upon which technique is determined to provide the best implementation. The description of the conversion process performed either on a record-by-record basis, record processing, or on a nonrecord This is determined by the functions selected in the algorithm modifier. Speciseparators in source perform blank padding or move record separator from controls to fying the record If neither of these functions is specified, in processing is to be performed. receiver indicates record that string processing is to be performed. indicates specified, it be which case decompression must The operation is basis, string processing. , The operation begins by accessing the bytes source of the source operand at the location specified by the offset. record processing is specified, the source offset may locate a point at which processing of a partially converted record is to be resumed or processing for a full record is to be started. The unconverted receiver record bytes field indicates whether conversion processing is to be started with a partial or a full record. Additionally, the transparency string active indicator in the conversion status procfield indicates whether conversion of a transparency string is active for the case of resumption of convercompleting the started by process is The conversion essing for a partially converted record. When sion of a partial source record When string processing is if necessary before processing the specified, the source offset is assumed first full source record. to locate the start of a compression entry. during the conversion process the end of the receiver operand ends with a resultant condition or receiver overrun. When is encountered, the instruction is specified in the algorithm modifier, this check is performed at the start of each record. A source exhausted condition would be detected before a receiver overrun condition if there is no source data to convert. If the receiver operand does not have room for a full record, the receiver overrun condition is recognized. The instruction is terminated with status in the When record processing conversion for Chapter 2. Computation and Branching Instructions 2=93 Convert controls operand describing the last completely converted record. is not performed. SNA to Character (CVTSC) For receiver overrun, partial conversion of a source record When string processing is specified in the algorithm modifier, then decompression must be specified and the decompression function described below defines the detection of receiver overrun. When during the conversion process the end of the source operand is encountered, the instruction ends with a resultant condition of source exhausted. See the description of this condition in the conversion process described below to determine the status of the controls operand values and the converted bytes in the receiver for each case. When string processing is specified, the bytes accessed from the source are converted on a string basis into the receiver operand at the location specified by the receiver offset. In this case, the decompression function must be specified and the conversion process is accomplished with just the decompression function defined below. When record processing is specified, the bytes accessed from the source are converted one record at a time into the receiver operand at the location specified by the receiver offset performing the functions -- specified in the algorithm modifier in the sequence defined by the following algorithm. Record separator conversion is performed as requested in the algorithm modifier during the initial record separator processing performed as each record is being converted. This provides for controlling the setting of the record separator value in the receiver. When the record separators in source option is specified, the following algorithm is used to locate A record separator is recognized in the source when a character value less than hex 40 is encountered. When do not perform decompression is specified, a source character value of hex 00 is recognized as a null value rather than as a record separator. In this case, the processing of the current record continues with the next source byte and the receiver is not updated. When perform data transparency conversion is specified, a character value of hex 35 is recognized as the start of a transparency string rather than as a record separator. them. If the do not put record separators into the receiver function is specified, the record separator, if any, from the source record being processed is removed from the converted form of the source record and will not be placed in the receiver. If the move record separators from the source to the receiver function is specified, the record separator from the source record being processed is left as is in the converted form of the source record and will be placed in the receiver. the translate record separators from the source to the receiver function is specified, the record sepaprocessed is translated using the specified translate table, replaced with its translated value in the converted form of the source record and, will be placed in the If rator from the source record being The translation receiver. performed as in the translate instruction with the record separator v alue serving as the source byte to be translated. It is used as an index into the specified translate table to select the byte in the translate table that contains the value to which the record separator is to be set. If the selected translate table byte is equal to hex FF, it is recognized as an escape code. The instruction ends with a resultant condition of escape code encountered, and the controls operand is set to describe the conversion status as of the processing completed just prior to the conversion step for the is record separator. If the selected translate table byte converted form of the record If the move record ratory alue is used is set to its is not equal to hex FF, the record separator in the value. separator from controls to receiver function is specified, the controls record sepain the converted form of the source record and will be placed into the receiver. Chapter 2. Computation and Branching Instructions 2-94 Convert SNA to Character (CVTSC) the record separators in source do blank padding function is requested, an assumed record sepwill be used if a record separator is missing in the source data. In this case, the controls record separator character is used as the record separator to precede the converted record if record separa- When arator in the receiver. The conversion process continues, bypassing the record sepathat would normally be performed. The condition of a missing record separator step conversion rator initial processing for a full record, the first byte of data is not a record sepaduring is detected when tors are to be placed rator character. Decompression performed is if the function converting strings of duplicate characters is in specified in This provides for the algorithm modifier. compressed format in the source back to their full size in the receiver. Decompression of the source data is accomplished by concatenating together character strings described by the compression strings occurring in the source. The source offset value is assumed to locate the start of a compression string. Processing of a partial decompressed record is performed if necessary. in the source by one or more comSCB (string control byte) possibly followed comprised of an are pression strings. Compression strings to be built into the receiver. character string by one or more bytes of data related to the strings to be built into the receiver are described The character The format . of an SCB and the description of the data that may follow it is as follows: SCB Char(1) — Bits 0-1 Control 00 = n nonduplicate characters are between this SCB and the next one; where n is the value of the count field (1-63). 01 = = Reserved. represents n deleted prime compression characters; where n is the value of the The next byte is the next SCB. 11 = This SCB represents n deleted duplicate characters; where n is the value of the count field (1-63). The next byte contains a specimen of the deleted characters. The byte fol10 This count SCB field (1-63). lowing the specimen character contains the next SCB. - Bits 2-7 Count This contains the or the invalid number number of characters that have been deleted for a prime or duplicate string, SCB for a nonduplicate string. A count value of zero is of characters to the next and results in the signaling of a conversion (hex 0C01) exception. Strings of prime compression characters or duplicate characters described in the decompressed character string the number of times indicated by the Strings of nonduplicate characters described in If the end of the source 0C01) exception is is the source are repeated SCB count value. the source record are formed into a decompressed SCB character string for the length indicated by the in count value. encountered prior to the end of a compression string, a conversion (hex signaled. record processing is specified, decompression is performed one record at a time. In this case, a conversion (hex 0C01) exception is signaled if a compression string describes a character string that would span a record boundary in the receiver. If the source contains record separators, the case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion as requested in the algorithm modifier is performed as the initial step in the building of the decompressed record. A record separator to be placed into the When , , addition to the data to be converted into receiver for the length specified in the receiver record length field. The decompression of compression strings from the source continues until a record separator character for the next record is recognized when the source contains record separa- receiver tors, or is in until the decompressed data required to fill the receiver record has been processed or the end Chapter 2. Computation and Branching instructions 2-95 Convert SNA to Character (CVTSC) of the source is encountered whether record separators are in the source or not. Transparency strings encountered in the decompressed character string are not scanned for a record separator value. If the end of the source is encountered, the data decompressed to that point appended to the optional record separator for this record forms a partial decompressed record. Otherwise, the decompressed character strings appended to the optional record separator for this record form the The conversion process then continues for this decompressed record. record with the next specified function. When string processing is specified, decompression is performed on a compression string basis with no record oriented processing implied. The conversion process for each compression string from the source is completed by placing the decompressed character string into the receiver. The conversion process continues decompressing compression strings from the source until the end of the source or the receiver is encountered. When the end of the source operand is encountered, the instruction ends with a resultant condition of source exhausted. When a character string cannot be completely contained in the receiver, the instruction ends with a resultant condition of receiver overrun. For either of the above ending conditions, the controls operand is updated to describe the status of the conversion operation as of the last completely converted compression entry. Partial conversion of a compression entry is not performed. Data transparency conversion is performed if perform data transparency conversion is specified in the algorithm modifier. This provides for correctly identifying record separators in the source even if the data for a record contains value that could be interpreted as record separator values. Processing of active transparency strings is performed if necessary. A nontransparent record is built by appending the nontransparent and transparent data converted from the record to the record separator for the record. The nontransparent record may be produced from either a partial record from the source or a full record from the source. This is accomplished by first accessing the record separator for a full record. The case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion as requested in the algorithm modifier is performed if it has not already been performed by a prior step; the rest of the source record is scanned for values of less than hex 40. A value greater than or equal to hex 40 the record being built as is. is considered nontransparent data and is concatenated onto A value equal to hex 35 identifies the start of a transparency string. A transparency string is comprised of 2 bytes of transparency control information followed by the data to be made transparent to scanning for record separators. The first byte has a fixed value of hex 35 and is referred to as the TRN (transparency) control character. The second byte is a 1-byte hexadecimal count, a value remaining from 1 to 255 decimal, of the number of bytes of data that follow and is referred to as the TRN count A TRN count of zero is invalid and causes a conversion (hex 0C01) exception. This contains the length of the transparent data and does not include the TRN control information length. The transparent data is concatenated to the nontransparent record being built and is not scanned for record separator charac. ters. A value equal to hex 00 is recognized as the record separator for the next record only when perform decompression is specified in the algorithm modifier. In this case, the nontransparent record is complete. When do not perform decompression is specified in the algorithm modifier, a value equal to hex 00 is ignored and is not included as part of the nontransparent data built for the current record. A value less than hex 40 but not equal to hex 35 is considered to be the record separator for the next record, and the forming of the nontransparent record is complete. The building of the nontransparent record receiver equals the receiver record length is if completed when the length of the data converted into the the record separator for the next record is not encountered prior to that point. Chapter 2. Computation and Branching Instructions 2-96 Convert SNA to Character (CVTSC) encountered prior to completion of building the nontransparent record, the nontransparent record built up to this point is placed in the receiver and the instruction ends with a resultant condition of source exhausted. The controls operand is updated to describe the status for the partially converted record. This includes describing a partially converted transparency string, if necessary, by setting the active transparency string status and the unconverted transparency string bytes If the end of the source is field. completed prior to encountering the end of the source, the conversion process continues with the blank padding function described below. If the building of the nontransparent record is padding is performed if the function is specified in the algorithm modifier This provides for expanding out to the size specified by the receiver record length the source records for which trailing blanks have been truncated. The padded record may be produced from either a partial record from the source or a full record from the source. k accessed. The case of a missing record separator in the source is detected as defined under the initial description of the conversion process. Record separator conversion as requested in the algorithm modifier, is performed if it has not already been performed by The record separator for this record is a prior step. The nontruncated data, if any, for the record is appended to the optional record separator for the record. The nontruncated data is determined by scanning the source record for the record separator for the next record. This scan is concluded after processing enough data to completely fill the receiver record or upon encountering the record separator for the next record. The data processed prior to concluding the scan The blanks, if is considered the nontruncated data for the record. any, required to pad the record out to the nontruncated data for the record, concluding the forming of the padded record. encountered during the forming of the padded record, the data processed up to that point, appended to the optional record separator for the record, is placed into the receiver and the instruction ends with a resultant condition of source exhausted. The controls operand is updated to describe the status of the partially converted record. If the end of the source If the forming of the padded record version of the record is is concluded prior to encountering the end of the source, the concompleted by placing the converted form of the record into the receiver. is At this point, either conversion of a source record has been completed or conversion has been interrupted due to detection of the source exhausted or receiver overrun condition. For record processing, if neither of the above conditions has been detected either during conversion of or at completion of conversion for the current record, the conversion process continues on the next source record with the decompression function described above. At completion of the instruction, the receiver offset locates the byte following the last converted byte in the receiver. The value of the remaining bytes in the receiver after the last converted byte are unpre- which conversion was completed. When record processing is specified, the unconverted receiver record bytes field specifies the length of the receiver record bytes not yet containing converted data. When perform data transparency conversion is specified in the algorithm modifier, the conversion status indicates whether converdictable. The source offset locates the byte following the last source byte for sion of a transparency string was active and the unconverted transparency string bytes the length of the remaining bytes to be processed for an active transparency string. field specifies in the source describing data that would span records in the receiver. SNA data from some systems may violate this restriction and as such be incompatible with the instruction. A provision can be made to avoid this incompatibility by performing the conversion of the SNA data through two invocations of this instruction. The first invoca- This instruction does not provide support for compression entries Chapter 2. Computation and Branching Instructions 2-97 SNA Convert Character (CVTSC) to would specify decompression with no record separator processing. The second invocation would specify record separator processing with no decompression. This technique provides for separating the tion decompression step from record separator processing; thus, the incompatibility This instruction can end with the escape code encountered condition. the user of the instruction will want to do some special processing In this is avoided. case, it expected that is for the record separator causing the have to set the appropriate condition. In order to resume execution of the instruction, the user will value for the record separator into the receiver and update the controls operand source offset and receiver offset fields correctly to provide for restarting processing at the right points in the receiver and source operands. For the special case of a tie between the source exhausted and receiver overrun conditions, the source exhausted condition is recognized first. That is, when source exhausted is the resultant condition, the receiver may also be full. In this case, the receiver offset may contain a value equal to the length specified for the receiver, which would cause an exception to be detected on the next invocation of the instruction. The processing performed for the source exhausted condition should provide for this case if the instruction is to be invoked multiple times with the same controls operand template. When the receiver overrun condition is the resultant condition, the source will always contain data that can be converted. This instruction will, in certain cases, ignore what would normally have been interpreted as a record separator value of hex 00. This applies (hex 00 is ignored) for the special case when do not perform decompression and record separators in source are specified in the algorithm modifier. Note that this does not apply when perform decompression is specified, or when do not perform decompression and no record separators in source and move record separator from controls to receiver are specified in the algorithm modifier. Limitations: Any form The following are limits that apply to the functions performed by this instruction. of overlap between the operands on this instruction yields unpredictable results in the receiver operand. Resultant Conditions * Source exhausted-The end of the source operand source can be converted, » Receiver overrun-An overrun condition in the receiver operand the source operand have been processed. • is encountered and no more bytes from the Escape code encountered-A record separator character is to be treated as an escape code. is is detected before encountered in ail of the bytes in the source operand that Exceptions Operands Exception 06 2 3 Other Addressing Spacing addressing violation X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X Argument/parameter XXX 01 08 1 01 Parameter reference violation Chapter 2. Computation and Branching Instructions 2-98 Convert SNA to Character (CVTSC) Operands Exception OC 01 10 1 damage Partial X state system object damage X Machine-dependent exception 03 Machine storage 22 limit X exceeded Machine support 02 Machine check X 03 Function check X XXX XXX XXX XXX XXX Object access 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Program execution X 04 Invalid branch target 2E Resource control limit 01 user profile storage limit 32 XXX Scalar type invalid Space management 01 38 X exceeded Scalar specification 01 36 Other Damage encountered 44 20 3 X Conversion 04 System object 1C 2 Computation X space extension/truncation Template specification 01 Template value X invalid Chapter 2. Computation and Branching Instructions 2-99 Copy Copy Bits Arithmetic Op Code Operand 1 Receiver 2 Source Operand 3 Operand 4 Offset Length Operand 1: Character variable scalar (fixed length) or numeric variable scalar. Operand 2: Character variable scalar (fixed length) or numeric variable scalar. Operand 3: Signed or unsigned binary immediate. Operand 4: Signed or unsigned binary immediate. Description: (CPYBTA) (CPYBTA) Operand (Hex) 102C Bits Arithmetic This instruction copies the signed bit string offset for a specified length right adjusted to the receiver source operand and pads on the starting at the specified left with the sign of the bit string source. The selected from the source operand are treated as an signed bits bit string and copied to the receiver value. The source operand can be character or numeric. The leftmost bytes of the source operand are used in the operation. The source operand is interpreted as a bit string with the bits numbered left to right from 0 to the total number of bits in the string minus 1. The offset operand indicates which cating the leftmost bit bit of the source operand is to be copied, with a offset of zero indiof the leftmost byte of the source operand. The length operand indicates the number of If the sum bits that are to be copied. of the offset plus the length exceed the length of the source an invalid operand length (hex will be raised. 2A0A) exception Limitations: The offset The length of the receiver cannot exceed four bytes. must have a non-negative value. The length operand must be an immediate value between 1 and 32. Exceptions Operands Exception 06 Spacing addressing violation X X 02 Boundary alignment violation X X 03 Range X X 06 Optimized addressability invalid X X 3 4 Other X X Argument/parameter 01 10 2 Addressing 01 08 1 Parameter reference violation Damage encountered 04 System object damage state X 44 X Partial system object damage Chapter 2. Computation and Branching instructions 2-100 Copy Bits Arithmetic (CPYBTA) Operands Exception 1C 1 03 Machine storage 20 22 2 3 4 Other Machine-dependent exception limit X exceeded Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X 03 Object suspended X X X X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-101 Copy Copy Operand (Hex) 101C Operand Source 1 Receiver 2 Operand 1: Character variable scalar (fixed length) or Operand 2: Character variable scalar (fixed length) Operand 3: Signed or unsigned binary immediate. Operand 4: Signed or unsigned binary immediate. Description: (CPYBTL) (CPYBTL) Bits Logical Op Code Bits Logical Copies the unsigned bit string Operand 3 Operand 4 Offset Length numeric variable scalar. or numeric variable scalar. source operand starting at the specified offset for a specified length to the receiver. _ If the receiver is shorter than the length, the left most bits are removed to make the source bit string conform to the length of the receiver. No exceptions are generated when truncation occurs. The selected bits from the source operand are treated as an unsigned adjusted to the receiver and padded on the left bit string and copied right with binary zeros. The source operand can be character or numeric. The leftmost bytes of the source operand are used in the operation. The source operand is interpreted as a bit string with the bits numbered left to right from 0 to the total number of bits in the string minus 1. The offset operand indicates which cating the leftmost bit bit of the source operand The length operand indicates the number of If the sum Limitations: offset bits that are to be copied. of the offset plus the length exceed the length of the source an invalid operand length (hex 2A0A) exception The to be copied, with a offset of zero indi- is of the leftmost byte of the source operand. will be signaled. The length of the receiver cannot exceed four bytes. must have a non-negative value. The length operand must be an immediate value between 1 and 32. Exceptions Operands Exception 06 1 2 X X 02 Boundary alignment violation X X 03 Range X X 06 Optimized addressability invalid X X X X X X Other Spacing addressing violation Argument/parameter 01 10 4 Addressing 01 08 3 Parameter reference violation Damage encountered Chapter 2. Computation and Branching Instructions 2-102 Copy Bits Logical (CPYBTL) Operands Exception 1 damage 04 System object 44 1C Partial 22 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X 03 Object suspended X X X Pointer specification Pointer does not exist 02 Pointer type invalid Resource control X X X X limit 01 user profile storage limit 36 Other Machine-dependent exception 01 2E 4 X 08 object compressed 24 3 X system object damage 03 Machine storage 20 2 state exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-103 Copy Copy Bits with Left Logical Shift Op Code Operand (Hex) 102F Bits with Left Logical Shift (CPYBTLLS) (CPYBTLLS) Operand Source 1 Receiver Operand 3 2 Shift control Operand 1: Operand 2: Character scalar or numeric scalar. Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. Character variable scalar or numeric variable scalar. This instruction copies the bit string value of the source operand to the bit string defined by the receiver operand with a left logical shift of the source bit string value under control of the shift control operand. Description: The operation results in copying the shifted receiver while padding the receiver with bit bit string value of the source to the bit string of the bit values of the source as values of 0 and truncating is appropriate for the specific operation. No indication is given of truncation of values truncated are 0 or bit values from the shifted source value. This is true whether the 1. The operation is performed such that the bit string of the source is considered to be extended on the left and right by an unlimited number of bit string positions of value 0. Additionally, a receiver bit view (window) with the attributes of the receiver is considered to overlay this conceptual bit source starting at the leftmost bit position of the original source value. A left logical shift of the conceptual bit string value of the source is then performed relative to the receiver bit string view according to the shift criteria specified in the shift control operand. After the shift, the bit string value then contained within the receiver bit string view is copied to the receiver. string string value of the The source and the receiver can be either character or numeric. preted as logical character strings. Due Any numeric operands are inter- to the operation being treated as a character string operation, the source operand may not be specified as a signed immediate operand. Additionally, for a source operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. shift control operand may be specified as an immediate operand, as a character(2) scalar, or as an unsigned binary(2) scalar. It provides an unsigned binary value indicating the number of bit positions for which the left logical shift of the source bit string value is to be performed. A zero value specifies no shift. The Exceptions Operands Exception 06 1 2 3 X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X Addressing 01 08 Spacing addressing violation Argument/parameter 01 10 Other Parameter reference violation Damage encountered Chapter 2. Computation and Branching Instructions 2-104 Copy Bits with Left Logical Shift (CPYBTLLS) Operands Exception 1 04 System object 44 1C Partial damage 22 X Machine-dependent exception limit exceeded X Machine support 02 Machine check X 03 Function check X Object access XXX XXX XXX XXX 03 Object suspended 08 object compressed Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control 36 exceeded X Scalar specification 01 X limit 01 user profile storage limit 32 Other X 02 Object destroyed 24 3 system object damage 03 Machine storage 20 2 state XXX Scalar type invalid Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-105 Copy Copy Bits with Right Arithmetic Shift Op Code 1 01 Operand (Hex) B Operand 2 Source Receiver 3 Shift Control Operand 1: Character variable or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. The Description: instruction copies the string value of the bit by the receiver operand with a right arithmetic shift control results in copying the shifted receiver while padding the receiver with the source, and truncating indication The operation bit is bit performed such that the bit string bit bit string value of the source to the values of 0 or is 1 of the bit string depending on the high order bit value of appropriate for the specific operation. values from the shifted source value. This is true whether the 1. value, with the value of the sign of source operand to the bit string defined bit string value under control of the of the source values of the source as given of truncation of is values truncated are 0 or number shift operand. The operation No (CPYBTRAS) (CPYBTRAS) Operand 1 Bits with Right Arithmetic Shift positions. bit A bit string of the source is considered a signed numeric binary of the source conceptuaily extended on the right arithmetic shift of the conceptual bit left an unlimited source string value of the is then performed according to the shift criteria specified in the shift control operand. No indication is given of truncation of bit values from the shifted conceptual source value. This is true whether the values truncated are 0 or 1. After the shift, the conceptual bit string value is then copied to the receiver, right aligned. Viewing the bit string value of the source and the bit string value copied to the receiver as signed numeric, the sign of the value copied to the receiver will be the same as the sign of the source. A right shift of one bit position is equivalent to dividing the signed numeric bit string value of the source by 2 with rounding downward, and assigning a signed numeric bit string equivalent to that result to the receiver. For example, if the signed numeric view of the source bit string is +9, shifting one bit position right yields +4. However if the signed numeric view of the source bit string is -9, shifting If all one bit position right yields -5. the significant bits of the conceptual source conceptual bit string value will be all zero bit string bits for positive are shifted out of the numbers, and all one field, the resulting bits for negative numbers. The source and the receiver can be either character or numeric. preted as logical character strings. Due Any numeric operands are inter- to the operation being treated as a character string operation, may not be specified as a signed immediate operand. Additionally, for a source operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. the source operand shift control operand may be specified as an immediate operand, as a character(2) scalar, or as a unsigned binary(2) scalar. It provides an unsigned binary value indicating the number of bit positions for which the right logical shift of the source bit string value is to be performed. A zero value specifies no shift. The Exceptions Chapter 2. Computation and Branching Instructions 2-106 Copy Bits with Right Arithmetic Shift (CPYBTRAS) Operands Exception 06 1 Addressing 01 03 Range 06 Optimized addressability invalid Argument/parameter 01 10 3 Parameter reference violation Damage encountered 04 System object damage state 44 1C Other XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment violation 08 2 Partial X system object damage X Machine-dependent exception 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X Object access XXX XXX XXX XXX 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 32 X Scalar specification 01 36 exceeded XXX Scalar type invalid Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-1 D7 Copy Copy Bits with Right Logical Shift Op Code Operand (Hex) Operand 2 3 Shift control Operand 1\ Character variable scalar or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3: Character(2) scalar (fixed length) or unsigned binary(2) scalar. Description: This instruction copies the by the receiver operand with a (CPYBTRLS) (CPYBTRLS) Operand Source 1 Receiver 103F Bits with Right Logical Shift value of the source operand to the bit string defined of the source bit string value under control of the shift bit string right logical shift control operand. The operation results in copying the shifted receiver while padding the receiver with bit source to the bit string of the values of 0 and truncating bit values of the source as bit string value of the is appropriate for the specific operation. No indication is given of truncation of values truncated are 0 or bit values from the shifted source value. This is true whether the 1. The operation is performed such that the bit string of the source is considered to be extended on the left and right by an unlimited number of bit string positions of value 0. Additionally, a receiver bit view (window) with the attributes of the receiver is considered to overlay this conceptual bit string value of the source starting at the leftmost bit position of the original source value. A right logical shift of the conceptual bit string value of the source is then performed relative to the receiver bit string view according to the shift criteria specified in the shift control operand. After the shift, the bit string value then contained within the receiver bit string view is copied to the receiver. string The source and the receiver can be either character or numeric. preted as logical character strings. Due Any numeric operands are inter- to the operation being treated as a character string operation, may not be specified as a signed immediate operand. Additionally, for a source operand specified as an unsigned immediate value, only a 1-byte immediate value may be specified. the source operand The shift control operand may be specified as an immediate operand, as a character(2) scalar, or as a It provides an unsigned binary value indicating the number of bit positions shift of the source bit string value is to be performed. A zero value specifies unsigned binary(2) scalar. for which the right logical no shift. Exceptions Operands Exception 06 1 2 3 X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X Argument/parameter XXX Addressing 01 08 01 10 Other Spacing addressing violation Parameter reference violation Damage encountered Chapter 2. Computation and Branching Instructions 2-108 Copy Bits with Right Logical Shift (CPYBTRLS) Operands Exception 1 damage 04 System object 44 1C Partial 22 3 X Machine-dependent exception limit X exceeded Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X X 03 Object suspended X X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X exceeded Scalar specification 01 36 X limit 01 user profile storage limit 32 Other X system object damage 03 Machine storage 20 2 state X Scalar type invalid X X Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-1 09 Copy Bytes Left-Adjusted (CPYBLA) Copy Bytes Left-Adjusted (CPYBLA) Op Code (Hex) Operand 10B2 1 Receiver Operand 2 Source Operand 1: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar, or data-pointer-defined numeric scalar. Operand 2. Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- defined numeric scalar. The logical string value of the source operand is copied to the logical string value of the receiver operand (no padding done). The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. Description: The length of the operation is equal to the length of the shorter of the two operands. The copying begins with the two operands left-adjusted and proceeds until the shorter operand has been copied. Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 1 and 2. The effect of specifying a null substring reference for either operand is that If no result either is set. operand is a character variable scalar, it may have a length as great as 16776191 bytes. Exceptions Operands Exception 06 01 08 Spacing addressing violation X X X X 03 Range X X 04 External data object not found X X 06 Optimized addressability invalid X X X X Parameter reference violation Damage encountered 44 Partial XXX XXX system object damage Machine-dependent exception 03 Machine storage 20 22 Other Argument/parameter 04 System object damage state 1C 2 02 Boundary alignment 01 10 1 Addressing limit exceeded Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X 01 Chapter 2. Computation and Branching Instructions 2-110 Copy Bytes Left-Adjusted (CPYBLA) Operands Exception 03 Object suspended 1 2 X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X exceeded Scalar specification 01 36 X limit 01 user profile storage limit 32 Other Scalar type invalid Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-111 Copy Bytes Left-Adjusted with Pad (CPYBLAP) Copy Bytes Left-Adjusted with Pad (CPYBLAP) Op Code (Hex) Operand 1063 Operand 1 Receiver Operand 1: Operand 2 Source 3 Pad Character variable scalar or numeric variable scalar, data-pointer-defined character numeric scalar. scalar, or data-pointer-defined Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- defined numeric scalar. Operand 3: Character scalar or numeric scalar. Description: The logical string value of the receiver operand (padded if source operand copied to the logical string value of the is needed). The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The length of the operation is equal to the length of the receiver operand. If the source operand is shorter than the receiver operand, the source operand is copied to the leftmost bytes of the receiver operand, and each excess byte of the receiver operand is assigned the single byte value in the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. If the source operand is longer than the receiver operand, the leftmost bytes of the source to the receiver operand) are copied to the receiver operand. operand (equal in length Substring operand references that allow for a null substring reference (a length value of zero) may be 1 and 2. The effect of specifying a null substring reference for the source is that the bytes of the receiver are each set with the single byte value of the pad operand. The effect of specifying a null substring reference for the receiver is that no result is set. specified for operands If either of the first two operands is a character variable scalar, it may have a length as great as 16776191. Exceptions Operands Exception 06 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 04 External data object not found X X 06 Optimized addressability invalid X X X X X X 04 System object damage state X X X X 44 X X X X 01 08 1C Other Spacing addressing violation Argument/parameter 01 10 1 Addressing Parameter reference violation Damage encountered Partial system object damage Machine-dependent exception Chapter 2. Computation and Branching Instructions 2-112 Copy Bytes Left-Adjusted with Pad (CPYBLAP) Operands 1 Exception 03 Machine storage limit exceeded 20 22 02 Machine check X 03 Function check X XXX XXX XXX XXX XXX Object access Object not found 03 Object suspended 08 object compressed Pointer specification 01 Pointer does not exist 02 Pointer type invalid Resource control X exceeded Scalar specification 01 36 X limit 01 user profile storage limit 32 Other X 02 Object destroyed 2E 3 Machine support 01 24 2 X Scalar type invalid X Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-113 Copy Bytes Overlap Left-Adjusted (CPYBOLA) Copy Bytes Overlap Left-Adjusted (CPYBOLA) Op Code Operand (Hex) 10BA Operand 1 Receiver 2 Source Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character variable scalar or numeric variable scalar. The logical string value of the source operand is copied to the logical string value of the receiver operand (no padding done). The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. Description: The length of the operation is equal to the length of the shorter of the two operands. The copying begins with the two operands left-adjusted and proceeds until the shorter operand has been copied. The excess bytes in the longer operand are not included in the operation. Predictable results occur even if two operands overlap because the source operand is, in effect, first copied to an intermediate result. Substring operand references that allow for a null substring reference (a length value of zero) may be 1 and 2. The effect of specifying a null substring reference for either operand is specified for operands that no result is set. Exceptions Operands Exception 06 01 08 Spacing addressing violation X X X 03 Range X X 06 Optimized addressability invalid X X X X X X X X X X Argument/parameter Parameter reference violation Damage encountered 44 Partial system object damage Machine-dependent exception 03 Machine storage 20 22 Other X 04 System object damage state 1C 2 02 Boundary alignment 01 10 1 Addressing limit exceeded X Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X 03 Object suspended X X 01 Chapter 2. Computation and Branching Instructions 2-114 Copy Bytes Overlap Left-Adjusted (CPYBOLA) Operands Exception 08 object compressed 24 Pointer does not exist 02 Pointer type invalid Resource control X X X X X exceeded Scalar specification 01 36 X Other limit 01 user profile storage limit 32 2 Pointer specification 01 2E 1 Scalar type invalid Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-115 Copy Bytes Overlap Left-Adjusted with Pad (CPYBOLAP) Copy Bytes Overlap Op Code (Hex) Left-Adjusted with Operand 10BB 1 Receiver Operand Pad (CPYBOLAP) Operand 2 Source Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character variable scalar or numeric variable scalar. Operand 3: Character scalar or numeric scalar. Description: The logical string value of the 3 Pad source operand is copied to the logical string value of the receiver operand. The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The length of the operation is equal to the length of the receiver operand. If the source operand is shorter than the receiver operand, the source operand is copied to the leftmost bytes of the receiver operand and each excess byte of the receiver operand is assigned the single byte value in the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. If the source operand is longer than the receiver operand, the leftmost bytes of the source operand (equal in length to the receiver operand) are copied to the receiver operand. Predictable results occur even if two operands overlap because the source operand copied to an intermediate result. is, in effect first Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 1 and 2. The effect of specifying a null substring reference for the source is that the bytes of the receiver are each set with the single byte value of the pad operand. The effect of specifying a null substring reference for the receiver is that no result is set. Exceptions 12 Operands Exception 06 Addressing 01 03 Range 06 Optimized addressability invalid Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object 44 1C Partial damage state system object damage X X X X X X X X X X Machine-dependent exception 03 Machine storage limit exceeded 20 Other XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment 08 3 Machine support 02 Machine check X Chapter 2. Computation and Branching Instructions 2-116 Copy Bytes Overlap Left-Adjusted with 12 Pad (CPYBOLAP) Operands Exception 03 Function check 22 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 Other XXX XXX XXX XXX XXX Object access 01 3 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-117 Copy Bytes Repeatedly (CPYBREP) Copy Bytes Repeatedly (CPYBREP) Op Code (Hex) Operand 10BE 1 Receiver Operand 1: Operand 2: Operand 2 Source Numeric variable scalar or character variable scalar Numeric scalar or character scalar (fixed-length). (fixed length). Description: The logical string value of the source operand is repeatedly copied to the receiver operand until the receiver is filled. The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The operation begins with the two operands left-adjusted and continues until the receiver operand is completely filled. If the source operand is shorter than the receiver, it is repeatedly copied from left to right (all or in part) until the receiver operand is completely filled. If the source operand is he receive operand, the leftmost bytes of the source operand (equal are copied to the receiver operand. longer than in length to the receiver operand) H Substring operand references that allow for a null substring reference (a length value of zero) may be operands 1 and 2. The effect of specifying a null substring reference for either operand specified for that If no result is is set. operand either is a character variable scalar, it may have a length as great as 16776191. Exceptions Operands Exception 2 1 06 01 Spacing addressing violation 02 Boundary alignment 03 Range 06 Optimized addressability invalid 08 Parameter reference violation Damage encountered 04 System object 44 1C Partial damage X X X X X X X X x XXX XXX state system object damage Machine-dependent exception 03 Machine storage 20 X Argument/parameter 01 10 limit exceeded Machine support 02 Machine check X 03 Function check 22 Other Addressing X Object access 01 Object not found 02 Object destroyed 03 Object suspended Chapter 2. X x X x X x Computation and Branching Instructions 2-118 Copy Bytes Repeatedly (CPYBREP) Operands 1 Exception 08 object compressed 24 Pointer does not exist 02 Pointer type invalid Resource control X X X X limit 01 user profile storage limit 36 Other X Pointer specification 01 2E 2 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-119 Copy Bytes Right-Adjusted (CPYBRA) Copy Bytes Right-Adjusted (CPYBRA) Op Code (Hex) Operand 10B6 Operand 1 Receiver 2 Source Operand 1: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar or data-pointer-defined numeric scalar. Operand 2: ’ Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointerH defined numeric scalar. The logical string value of the source operand is copied to the logical string value of the receiver operand (no padding done). The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. Description: The length of the operation is equal to the length of the shorter of the two operands. The rightmost bytes (equal to the length of the shorter of the two operands) of the source operand are copied to the 8 °f r6CeiVer ° Perand eXCeSS byteS in the ionger operand are not included in Z ^ ^ ' operatioT ^ Substring operand references that allow for a null substring reference (a length value of zero) may be 6 dS 1 2 ° f Specifying a nul1 substrin 9 reference for either operand ^ tâTno ' is re s°ul Hsêt" Exceptions Operands Exception 06 01 Spacing addressing violation 02 Boundary alignment 03 Range 04 External data object not found 06 Optimized addressability invalid 08 Parameter reference violation Damage encountered 04 System object 44 1C 2 X X X X X X Other X x X x X X Argument/parameter 01 10 1 Addressing Partial damage XXX XXX state system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 Machine support 02 Machine check X 03 Function check 22 X Object access 01 Object not found 02 Object destroyed Chapter 2. X X X X Computation and Branching Instructions 2-120 Copy Bytes Right-Adjusted (CPYBRA) Operands Exception 03 Object suspended 1 2 X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X exceeded Scalar specification 01 36 X limit 01 user profile storage limit 32 Other X Scalar type invalid X Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-121 Copy Bytes Right-Adjusted with Pad (CPYBRAP) Copy Bytes Right-Adjusted with Pad (CPYBRAP) Op Code (Hex) Operand 1067 1 Receiver Operand 2 Source Operand 3 Pad Operand 1: Character variable scalar, numeric variable scalar, data-pointer-defined character scalar or data-pointer-defined numeric scalar. Operand 2: Character scalar, numeric scalar, data-pointer-defined character scalar, or data-pointer- defined numeric scalar. Operand 3: Character scalar or numeric scalar. Description: The logical string value of the source operand is copied to the logical string value of the receiver operand (padded if needed). The operands can be either character or numeric. Any numeric operands are interpreted as logical character strings. The length of the operation is equal to the length of the receiver operand. If the source operand is shorter than the receiver operand, the source operand is copied to the rightmost bytes of receiver operand, and each excess byte is assigned the single byte value in the pad operand. If the pad operand is more than 1 byte in length, only its leftmost byte is used. If the source operand is longer an the receiver operand, the rightmost bytes of the source operand (equal in length to the receiver operand) are copied to the receiver operand. Substring operand references that allow for a null substring reference (a length value of zero) may be operands 1 and 2. The effect of specifying a null substring reference for the source is that the bytes of the receiver are each set with the single byte value of the pad operand. The effect of specifying a null substring reference for the receiver is that no specified for result is set. Exceptions 12 Operands Exception 06 Addressing 01 03 Range 04 External data object not found 06 Optimized addressability invalid Argument/parameter 01 10 Parameter reference violation 44 Partial system object damage X X X X X X X X X Machine-dependent exception 03 Machine storage limit exceeded 20 X Damage encountered 04 System object damage state 1C Other XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment 08 3 X Machine support 02 Machine check X 03 Function check X Chapter 2. Computation and Branching Instructions 2-1 22 Copy Bytes Right- Ad justed with Pad (CPYBRAP) Operands 1 Exception 22 Object not found 02 Object destroyed 03 Object suspended Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X exceeded Scalar specification 01 36 X limit 01 user profile storage limit 32 Other X 08 object compressed 24 3 XXX XXX XXX Object access 01 2 X Scalar type invalid X Space management 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-123 Copy Bytes Copy Bytes Op Code to Bits Arithmetic (Hex) Operand 104C (CPYBBTA) (CPYBBTA) Operand 1 Receiver Operand 2 3 Operand 4 Offset Length (fixed length) or numeric variable scalar. Operand 1 Operand 2: Signed binary immediate or unsigned binary immediate. Operand 3: Signed binary immediate or unsigned binary immediate. Operand 4: Character variable scalar Character variable scalar to Bits Arithmetic (fixed length) Source or numeric variable scalar. Description: This instruction copies a byte string from the source operand to a receiver operand. The source operand the to left fit is interpreted as a signed binary value and into the bit string in the receiver operand. No may be indication is bit string in the sign extended or truncated on given when truncation occurs. The location of the bit string in the receiver operand is specified by the offset operand. The value of e offset operand specifies the bit offset from the start of the receiver operand to the start of the bit string. Thus, an offset operand value of 0 specifies that the bit string starts at the leftmost bit position of the receiver operand. The length of the bit string in the receiver operand is specified by the length operand. The value of the length operand specifies the length of the bit string in bits. Limitations: If The following are the source operand and the A source operand If A limits that bit string in longer than 4 bytes the offset operand is apply to the functions performed by this instruction. the receiver operand overlap, the results are unpredictable. may not be specified. signed binary immediate, a negative value length operand with a value less than 1 or greater than 32 may may not be specified. not be specified. The bit string specified by the offset operand and the length operand receiver operand. may not extend outside the Exceptions Operands Exception 1 06 4 X X 02 Boundary alignment violation X X X X X X X X 03 Range 06 Optimized addressability invalid Other Argument/parameter 01 10 3 Spacing addressing violation 01 08 2 Addressing Parameter reference violation Damage encountered Chapter 2. Computation and Branching Instructions 2-124 Copy Bytes to Bits Arithmetic (CPYBBTA) Operands 1 Exception 04 System object 44 1C Partial damage 22 3 4 state X Machine-dependent exception limit X exceeded Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X 03 Object suspended X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 36 Other X system object damage 03 Machine storage 20 2 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-125 Copy Bytes Copy Bytes Op Code to Bits Logical (Hex) Operand 1030 (CPYBBTL) (CPYBBTL) Operand 1 Receiver 2 Offset Operand 3 Operand 4 Length Source Operand /: Operand 2: Signed binary immediate or unsigned binary immediate. Operand 3: Signed binary immediate or unsigned binary immediate. Operand 4\ Character variable scalar Description: to Bits Logical Character variable scalar (fixed length) or numeric variable scalar. (fixed length) or numeric variable scalar. This instruction copies a byte string from the source operand to a bit string in the receiver operand. The source operand or truncated on the is left . interpreted as an unsigned binary value and may be padded on the left with 0's to fit into the bit string in the receiver operand. No indication is given when truncation occurs. The location of the bit string in the receiver operand is specified by the offset operand. The value of the offset operand specifies the bit offset from the start of the receiver operand to the start of the bit string. Thus, an offset operand value of 0 specifies that the bit string starts at the leftmost bit position of the receiver operand. The length of the bit string in the receiver operand is specified by the length operand. The value of the length operand specifies the length of the bit string in bits. Limitations: If A If A The following are the source operand and the limits that bit string in source operand longer than 4 bytes the offset operand is bit string the receiver operand overlap, the results are unpredictable. may not be specified. signed binary immediate, a negative value length operand with a value less than The apply to the functions performed by this instruction. 1 or greater than 32 specified by the offset operand and the length may may not be specified. not be specified. operand may not extend outside the receiver operand. Exceptions Operands Exception 06 3 4 Spacing addressing violation X X X X 03 Range X X 06 Optimized addressability invalid X X Other X X Argument/parameter 01 10 2 02 Boundary alignment violation 01 08 1 Addressing Parameter reference violation Damage encountered Chapter 2. Computation and Branching Instructions 2-126 Copy Bytes to Bits Logical (CPYBBTL) Operands Exception 04 System object 44 1C Partial 1 damage 22 3 4 X Machine-dependent exception limit X exceeded Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X 03 Object suspended X X X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 36 Other X system object damage 03 Machine storage 20 2 state X exceeded Space management X 01 space extension/truncation Chapter 2, Computation and Branching Instructions 2-1 27 Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) Op Code Operand (Hex) 1053 Operand Source 1 Receiver Operand /: Data-pointer-defined character scalar. Operand 2: Data-pointer-defined character scalar. Operand 3: Character(3) scalar or Description: Operand 2 3 Pad null. The extended character string value of the source operand is copied to the receiver operand. The operation is performed at the length of the receiver operand. If the source operand is shorter than the receiver, the source operand is copied to the leftmost bytes of the receiver and the excess bytes of the receiver are assigned the appropriate value from the pad operand. The pad operand, operand • if 3, is three bytes in length and has the following format: Pad operand Char(3) - Single byte pad value Char(1) — Double byte pad value Char(2) the pad operand a null byte, is more than three bytes in length, only its pad operand results in default pad values of hex 40, for being used. The single byte pad value and the first byte leftmost three bytes are used. Specifying single byte, and hex 4040, for double of the double bvte pad value cannot be (SO = hex 0E) value or a shift in control character (SI = hex OF) value. Specification of such an invalid value results in the signaling of the scalar value invalid (hex 3203) exception. either a shift out control character Operands 1 acter data field Support for instruction. results in and 2 must be specified as Data Pointers which define either a simple (single byte) charor one of the extended (double byte) character data fields. usage of a Data Pointer defining an extended character scalar value is limited to this of such a data pointer defined value on any other instruction is not supported and Usage the signaling of the scalar type invalid (hex 3201) exception. For more information on support for extended character data butes, Materialize Pointer, and Create Cursor instructions. fields, refer to the Set Data Pointer Attri- Four data types are supported for data pointer definition of extended (double byte) character fields, OPEN, EITHER, ONLYNS and ONLYS. Except for ONLYNS, the double byte character data must be surrounded by a shift out control character (SO hex 0E) and a shift in control character (SI = hex OF). • The ONLYNS • The ONLYS field can only contain double byte character data within a SO. .SI • The EITHER field can consist of double byte character or single byte character data but only one double byte character data is present it must be surrounded by an SO SI pair. field type at a time. If only contains double byte data with no SO, SI delimiters surrounding it. pair. .. The OPEN can consist of a mixture of double byte character and single byte character data. double byte character data is present it must be surrounded by an SO SI pair. field If .. Specifying an extended character value which violates the above restrictions results the invalid extended character data (hex 0C12) exception. Chapter 2. in the signaling of Computation and Branching Instructions 2-1 28 Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) The copy operations which can be specified on valid this instruction are the following; Op 1 Onlyns Onlys Open Figure Either Onlyns yes yes yes yes Onlys yes yes yes yes Open no no yes no Either no no yes yes Valid copy operations for 2-5. CPYECLAP Specifying a copy operation other than the valid operations defined above results the invalid extended character operation (hex 0C13) exception. When part of the When is the signaling of source of type ONLYNS (no SO/SI delimiters) being copied to a not ONLYNS, SO and SI delimiters are implicitly added around the source value as the copy operation receiver which in is for a copy operation. the source value is longer than can be contained in the receiver, truncation is necessary and the following truncation rules apply: 1. 2. Truncation When the when the is on the right (like simple character copy operations). string to be truncated receiver ONLYNS, is is a single byte character string, or an extended character string bytes beyond those that into the receiver are truncated with fit no further processing needed. 3. When a. When byte b. is an extended character string and the receiver end of the receiver are truncated as follows: the string to be truncated the bytes that at the fall the last byte that would is fit in the receiver truncated and replaced with an is the first is not ONLYNS, byte of an extended character, that SI character. the last byte that would fit in the receiver is the second byte of an extended character, both bytes of that extended character are truncated and replaced with a SI character followed by a single byte pad value. This type of truncation can only occur when converting to an OPEN When field. When sary. 1. the source value One is shorter than that which can be contained of three types of padding Double byte (DB) - is in the receiver, padding is neces- performed: the source value padded on the is right with double byte pad values out to the length of the receiver. 2. Double byte concatenated with a SI value (DB| jSI) - the source double byte value is padded on the right with double byte pad values out to the second to last byte of the receiver and an SI delimiter is 3. placed in the last byte of the receiver. Single byte (SB) - the source value is padded on the right with single byte pad values out to the length of the receiver. The type of padding performed is determined by the type of operands involved in the operation: 1. If the receiver is ONLYNS, DB padding 2. If the receiver is ONLYS, DB||SI padding 3. If the receiver is EITHER and the source contained is EITHER and the source contained a single byte value, SB padding is performed. will be performed. a double byte value, DB||SI padding is performed. 4. If the receiver Chapter 2. is performed. Computation and Branching Instructions 2-129 Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 5. If the receiver is OPEN, SB padding is performed. The above padding rules cover all the operand combinations which are allowed on the instruction. A complete understanding of the operand combinations allowed (prior diagram), and the values can be contained in the different operand types the valid combinations. is which necessary to appreciate that these rules do cover all Exceptions Operands Exception 06 01 08 2 3 Spacing addressing violation X X X 02 Boundary alignment X X X 03 Range X X X 04 External data object not found X X 06 Optimized addressability invalid X X X X X X Parameter reference violation Computation 12 Invalid extended character data X 13 Invalid extended character operation 10 44 Partial damage 22 state system object damage X X X X X X X X Machine-dependent exception 03 Machine storage 20 X Damage encountered 04 System object 1C limit exceeded X Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X X 03 Object suspended X X X 01 X 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X limit 01 user profile storage limit 32 Other Argument/parameter 01 OC 1 Addressing exceeded X Scalar specification 01 Scalar type invalid 01 Scalar value invalid X X X Chapter 2. Computation and Branching Instructions 2-130 Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) 12 Operands Exception 36 3 Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-131 Copy Hex Copy Hex Op Code Digit Numeric Operand (Hex) 1092 to /: Operand 2: Numeric to Numeric (CPYHEXNN) Numeric (CPYHEXNN) Operand 1 Receiver Operand Digit 2 Source Numeric variable scalar or character variable scalar Numeric scalar or character scalar (fixed-length). (fixed-length). The numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the source operand is copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the receiver operand. The operands can be either character strings or numeric. Any numeric Description: operands are interpreted as logical character strings. Exceptions Operands Exception 06 1 2 X X 02 Boundary alignment X X 03 Range X X 06 Optimized addressability invalid X X X X 01 08 Spacing addressing violation Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object 44 1C Other Addressing Partial damage XXX XXX state system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X 03 Object suspended X X X X X X 01 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 exceeded X Space management Chapter 2 . Computation and Branching Instructions 2-132 Copy Hex Digit Numeric to Numeric (CPYHEXNN) Operands Exception 01 1 2 Other X space extension/truncation Chapter 2. Computation and Branching Instructions 2-133 Copy Hex Copy Hex Op Code Digit Numeric Operand (Hex) 1096 to Digit Numeric to Zone (CPYHEXNZ) Zone (CPYHEXNZ) Operand 1 Receiver 2 Source Operand 1: Numeric variable scalar or character variable scalar Operand 2: Numeric scalar or character scalar (fixed-length). (fixed-length). The numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the source operand is copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by the receiver operand. The operands can be either character strings or numeric. Any numeric Description: I operands are interpreted as logical character strings. 1 Exceptions Operands Exception 06 1 2 Addressing 01 Spacing addressing violation 02 Boundary alignment 03 Range 06 Optimized addressability invalid 08 Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object 44 1C Partial damage state system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 Machine support 02 Machine check 03 Function check 22 Object access 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit 36 exceeded Space management Chapter 2. Computation and Branching Instructions 2-134 Copy Hex Digit Numeric to Zone (CPYHEXNZ) Operands Exception 01 1 space extension/truncation 2 Other X Chapter 2. Computation and Branching Instructions 2-135 Copy Hex Copy Hex Op Code Digit Operand (Hex) Operand 1 Receiver 1: Operand 2: Zone To Numeric (CPYHEXZN) Zone To Numeric (CPYHEXZN) 109A Operand Digit 2 Source Numeric variable scalar or character variable scalar Numeric scalar or character scalar (fixed-length). (fixed-length). The zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the source copied to the numeric hex digit value (rightmost 4 bits) of the leftmost byte referred to by Description: operand is the receiver operand. The operands can be either character strings or numeric. Any numeric operands are interpreted as logical character strings. Exceptions Operands Exception 06 Spacing addressing violation X X X X 03 Range X X 06 Optimized addressability invalid X X X X X X X X X X Argument/parameter Parameter reference violation Damage encountered damage 04 System object 44 1C Partial state system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 22 X Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X 03 Object suspended X X 01 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Other 02 Boundary alignment 01 10 2 Addressing 01 08 1 Resource control X X X X limit 01 user profile storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-136 Copy Hex Digit Zone To Numeric (CPYHEXZN) Operands Exception 36 Space 01 1 2 Other management X space extension/truncation Chapter 2, Computation and Branching Instructions 2-137 Copy Hex Copy Hex Op Code Digit Operand (Hex) Operand 2 Source 1 Receiver /: Operand 2: Zone To Zone (CPYHEXZZ) Zone To Zone (CPYHEXZZ) 109E Operand Digit Numeric variable scalar or character variable scalar Numeric scalar or character scalar (fixed-length). (fixed-length). The zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the source copied to the zone hex digit value (leftmost 4 bits) of the leftmost byte referred to by the receiver operand. Description: operand is The operands can be either character strings or numeric. Any numeric operands are interpreted as logical character strings. Exceptions Operands Exception 06 01 Spacing addressing violation X X X X 06 Optimized addressability invalid X X Other X X Argument/parameter Parameter reference violation Damage encountered XXX XXX 04 System object damage state 44 1C X X 01 10 2 03 Range 02 Boundary alignment 08 1 Addressing Partial system object damage Machine-dependent exception 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X Object access Object not found X X 02 Object destroyed X X 03 Object suspended X X X X X X 01 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-138 Copy Hex Digit Zone To Zone (CPYHEXZZ) Operands Exception 36 Space 01 1 2 Other management space extension/truncation X Chapter 2. Computation and Branching Instructions 2-139 Copy Numeric Value (CPYNV) Copy Numeric Value (CPYNV) Op Code CPYNV (Hex) Receiver Operand Source Receiver Source Branch options Receiver Source Branch targets Branch options Receiver Source Branch targets Indicator options Receiver Source Indicator targets Indicator options Receiver Source Indicator targets Operand Extender 1 2 Operand [3-6] 1042 CPYNVR 1242 CPYNVB 1C42 CPYNVBR 1 E42 CPYNVI 1842 CPYNVIR 1 A42 Operand 1: Operand 2: Operand 3-6: Numeric variable scalar or data-pointer-defined numeric Numeric scalar or data pointer-defined-numeric 9 Branch Form- Branch number. 9 Indicator i scalar. scalar. point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. avwcoo LBCPYNV ( var receiver : var recei ver_attributes var source var source attributes : : : any numeric type; aggregate ; any numeric type; aggregate ; ) Description: The numeric value of the source operand is copied to the numeric receiver operand. Both operands must be numeric. If necessary, the source operand is converted to the same type as the receiver operand before being copied to the receiver operand. The source value is adjusted to the length of the receiver operand, aligned at the assumed decimal point of the receiver operand, or both before being copied to significant digits are truncated on the end of the source value, a size OCOA) exception may be suppressed by using the suppress binary size exception program attribute on the Create Program (CRTPG) instruction. (hex OCOA) exception it. is If signaled. When the receiver is left binary, this size (hex If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled or if the size (hex OCOA) exception is suppressed, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. Chapter 2. Computation and Branching Instructions 2-140 Copy Numeric Value (CPYNV) Conversions between floating-point integers and integer formats (binary or decimal with no fractional digits) is exact, except when an exception is signaled. OCOC) exception is signaled when an attempt is made to convert from floating-point to binary or decimal and the result would represent infinity or NaN, or nonzero digits would be truncated from the left end of the resultant value. An invalid floating-point conversion (hex For the optional round form of the instruction, a floating-point receiver operand is invalid. For a fixed-point operation, if significant digits are truncated from the left end of the source value, a size (hex OCOA) exception is signaled. When the receiver is binary, this size (hex OCOA) exception may be suppressed by using the suppress binary size exception program attribute on the Create Program (CRTPG) instruction. For a floating-point receiver, if the exponent of the resultant value is too large or too small to be represented in the receiver field, the floating-point overflow (hex 0C06) and floating-point underflow (hex 0C07) exceptions are signaled, respectively. Resultant Conditions » Positive-The algebraic value of the numeric scalar receiver operand • Negative-The algebraic value of the numeric scalar receiver operand • Zero-The algebraic value of the numeric scalar receiver operand • Unordered-The value assigned a floating-point receiver operand is is is positive. is negative. zero. NaN. Exceptions Operands 1 2 X X 02 Boundary alignment X X 03 Range X X 04 External data object not found X X 06 Optimized addressability invalid X X X X Exception 06 Addressing 01 08 Spacing addressing violation Argument/parameter 01 OC Parameter reference violation Computation X 02 Decimal data 10 Other 06 Floating-point overflow X 07 Floating-point underlow X 09 Floating-point invalid operand X 0A Size X 0C Invalid floatin-point conversion X 0A Floating-point inexact result X X Damage encountered 04 System object damage state 44 Partial system object damage Chapter 2. X X X X X X Computation and Branching Instructions 2-141 Copy Numeric Value (CPYNV) Operands Exception 1C 1 03 Machine storage 20 22 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access 01 Object not found XXX XXX XXX XXX X 02 Object destroyed 03 Object suspended 08 object compressed 24 X X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Program execution 04 Invalid branch target 2E Resource control exceeded X Scalar specification 01 36 X limit 01 user profile storage limit 32 Other 2 Machine-dependent exception Scalar type invalid X X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-142 Decompress Data (DCPDATA) Decompress Data (DCPDATA) Op Code Operand 1 Decompress Data (Hex) 1051 template Operand — 1: Space pointer. ILE access DCPDATA ( decompress_data_template : space pointer ) The instruction decompresses user data. Operand 1 identifies a template which identithe data to be decompressed. The template also identifies the result space to receive the decom- Description: fies pressed data. The Decompress Data template must be aligned on a 16-byte boundary. The format is as follows: Char(4) • Reserved {binary ® Result area length Bin(4) • Actual result length Bin(4)* ® Reserved (binary Char(20) ® Source space pointer Space pointer 9 Result space pointer Space pointer Note: 0) 0) input value associated with template entries annotated with an asterisk (*) are ignored by the instruction; these fields are updated by the instruction to return information about instruction The execution. by the source space pointer is decompressed and stored at the pointer The actual result length is set to the number of bytes space result the location specified by data is not modified. Source the decompressed result. The The data The at the location specified result area length field value supplied in the template because must be greater than zero. The length of the source data this length is contained within the compressed data. is in not the decompressed result data will not fit in the result area (as specified by the result area length), the decompression is stopped and only as many decompressed bytes as will fit in the result area are stored. The actual result length is always set to the full length of the result, which may be larger than If the result area length. The compressed data (previously compressed with CPRDATA) contains a signature which is checked by DCPDATA. The signature indicates which compression algorithm was used to compress the data. exception is signaled. It is possible If the signature is invalid, an invalid compressed data (hex 0C14) data has been corrupted. In almost all compressed the though valid even appears that the signature (hex 0C14) exception. Data data compressed invalid signal the will cases, the DCPDATA instruction algorithm applied to the cordecompression when the the case corruption will not be detected only in bytes. decompressed rupted data produces the correct number of It is (that not possible to corrupt the is, function check) or fail compressed data to terminate (that in is, such a way that the DCPDATA instruction would fail loop). Chapter 2. Computation and Branching Instructions 2-143 Decompress Data (DCPDATA) Authorization Required • None Lock Enforcement • None Exceptions Operands Exception 06 01 08 space addressing violation X X X 06 optimized addressability invalid X Argument/Parameter Parameter reference violation X Computation compressed data X Damage encountered 44 1C X 03 range 14 invalid 10 Other 02 boundary alignment 01 OC 1 Addressing partial system object damage X Machine-dependent exception 03 machine storage limit exceeded 20 22 X Machine support 02 machine check X 03 function check X Object access 02 object destroyed X X 03 object suspended X X 08 object compressed 24 does not exist X X 02 pointer type invalid X X 03 pointer addressing invalid object X X Resource control limit 01 user profile storage limit 36 exceeded X Space management 01 38 X Pointer specification 01 pointer 2E X space extension/truncation X X Template specification 01 template value invalid X Chapter 2. Computation and Branching Instructions 2-144 Decompress Data (DCPDATA) Operands 1 Exception 44 Other Domain 01 object X domain error Chapter 2. Computation and Branching Instructions 2-145 Divide (DIV) Divide (DSV) Op Code (Hex) Extender Operand Operand 1 Operand 2 3 Operand [4-7] DIV 104F Quotient Dividend Divisor DIVR Quotient Dividend Divisor Quotient Dividend Divisor Indicator targets Quotient Dividend Divisor Indicator targets 124F DIVI Indicator 184F options DIVIR Indicator 1A4F options DIVB 1C4F Branch options Quotient Dividend Divisor Branch targets DIVBR Branch options Quotient Dividend Divisor Branch targets 1 E4F Operand 1 Operand 2: Numeric scalar. Operand 3: Numeric scalar. Operand 4-7: Numeric variable : • Branch Form - Branch number. * Indicator scalar. point, instruction pointer, relative instruction Form - Numeric variable scalar or character number, or absolute instruction variable scalar. Short forms Op Code (Hex) Extender DIVS 1 Operand Operand 1 Quotient/Dividend Divisor Quotient/Dividend Divisor 2 Operand [3-6] 14F DIVSR 134F DIVIS 194F Indicator options Quotient/Dividend Divisor Indicator targets DIVISR Indicator options Quotient/Dividend Divisor Indicator targets DIVBS 1 D4F Branch options Quotient/Dividend Divisor Branch targets DIVBSR Branch options Quotient/Dividend Divisor Branch targets 1 1 B4F F4F Operand 1: Numeric variable scalar. Chapter 2 . Computation and Branching Instructions 2-146 Divide (DIV) Numeric Operand 2: Operand 3-6: scalar. Branch Form - Branch number. . • Indicator Description: point, instruction pointer, relative instruction Form - Numeric variable scalar or character The Quotient Operands can have is number, or absolute instruction variable scalar. the result of dividing the Dividend by the Divisor. floating-point, packed or zoned decimal, signed or unsigned binary type. Source operands are the Dividend and Divisor. The receiver operand is the Quotient. operands are not of the same type, source operands are converted according to the following If 1. If any one of the operands has floating point type, source operands are converted to rules: floating point type. 2. 3. any one of the operands has zoned or packed decimal type, source operands are converted to packed decimal. Otherwise, if Otherwise, the binary operands are converted to a logically treated as signed binary{4) scalars. like type. Note; unsigned binary(2) scalars are Source operands are divided according to their type. Floating point operands are divided using division. Unsigned floating point division. Packed decimal operands are divided using packed decimal using binary division is used with unsigned source operands. Signed binary operands are divided two's complement binary division. binary Better performance can be obtained if all operands have the same type. Signed and unsigned division execute faster than either packed decimal or floating point division. Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. the divisor has a numeric value of zero, a zero divide (hex OCOB) or floating-point zero divide (hex OCOE) exception is signaled respectively for fixed-point versus floating-point operations, if the dividend has a value of zero, the result of the division is a zero quotient value. If the divisor has a numeric value of 0, a zero divide (hex OCOB) exception has a value of 0, the result of the division is a zero value quotient. If is signaled. If the dividend For a decimal operation, the precision of the result of the divide operation is determined by the number of fractional digit positions specified for the quotient. In other words, the divide operation will be performed so as to calculate a resultant quotient of the same precision as that specified for the and quotient operand. If necessary, internal alignment of the assumed decimal point for the dividend performed to ensure the correct precision for the resultant quotient value. These exception. An internal internal alignments are not subject to detection of the decimal point alignment specified for quotient value will be calculated for any combination of decimal attributes which may be operand is subject to the instruction's operands. However, the assignment of the result to the quotient 31 detection of the size (hex 0C0A) exception thereby limiting the assignment to, at most, the rightmost divisor operands is digits of the calculated result. Floating-point division uses exponent subtraction and significand division. If the dividend operand is shorter than the divisor operand, it is logically adjusted to the length of the divisor operand. Chapter 2. Computation and Branching Instructions 2-147 Divide (DIV) For fixed-point computations and for the significand division of a floating-point computation, the division is performed according to the rules of algebra. Unsigned binary is treated as a positive number for the algebra. operation For a floating-point computation, the operation The result of the operation that used is performed as if to infinite precision. is copied into the quotient operand. If this operand is not the same type as performing the operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the length of the quotient operand, aligned at the assumed decimal point of the quotient operand, or both before being copied to it. If significant digits are truncated on the left end of the resultant value, a size (hex OCOA) exception is signaled. in If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. For the optional round form of the instruction, specification of a floating-point receiver operand is invalid. For fixed-point operations nonzero digits are in programs truncated from the that request to be notified of size (hex left OCOA) exceptions, if end of the resultant value, a size (hex OCOA) exception is signaled. For floating-point operations that involve a fixed-point receiver field, if nonzero digits would be trunleft end of the resultant value, an invalid floating-point conversion (hex OCOC) exception cated from the is signaled. For a floating-point quotient operand, if the exponent of the resultant value is either too large or too small to be represented in the quotient field, the floating-point overflow (hex 0C06) and floating-point underflow (hex 0C07) exceptions are signaled, respectively. Resultant Conditions • Positive-The algebraic value of the numeric scalar quotient • Negative-The algebraic value of the numeric scalar quotient * * Zero-The algebraic value of the numeric scalar quotient is is is positive. negative. or zero. Unordered-The value assigned a floating-point quotient operand is NaN. Exceptions 12 Operands Exception 06 Addressing 01 03 Range 06 Optimized addressability invalid Argument/parameter 01 0C Other XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment 08 3 Parameter reference violation Computation 02 Decimal data X 06 Floating-point overflow X X Chapter 2. Computation and Branching Instructions 2-148 Divide (DIV) 12 Operands Exception 07 Floating-point underlow X 09 Floating-point invalid operand XXX X OB Zero divide 0C Invalid floatin-point conversion X 0D Floating-point inexact result X X 0E Floating-point divide by zero Damage encountered 04 System object 44 1C Partial damage state system object damage X X X X X X X X Machine-dependent exception X 03 Machine storage limit exceeded 20 Machine support X 02 Machine check X 03 Function check 22 XXX XXX XXX XXX XXX Object access 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Resource control X limit 01 user profile storage limit 36 X Program execution 04 Invalid branch target 2E Other X 0A Size 10 3 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-149 Divide with Remainder (DIVREM) Divide with Remainder (DIVREM) Op Code Extender Operand Operand 1 Operand 2 (Hex) DIVREM Dividend Divisor Remainder Quotient Dividend Divisor Remainder Quotient Dividend Divisor Remainder 1274 DIVREMI Indicator 1874 options Operand 4 Quotient 1074 DIVREMR 3 Operand [5-7] Indicator targets DIVREMIR Indicator 1A74 options Quotient Dividend Divisor Remainder Indicator targets DIVREMB Branch 1C74 options Quotient Dividend Divisor Remainder Branch targets DIVREMBR 1 Branch E74 Quotient Dividend Divisor Remainder options Branch targets Operand 1: Operand 2: Numeric scalar. Operand 3: Numeric scalar. Operand 4: Numeric variable Operand 5-7: Numeric variable scalar. scalar. F° rm BranCh * ' nStrUCti ° n pointer number Indicator Op Code (Hex) DIVREMS Extender Operand Indicator 1974 options B74 Quotient/Dividend Divisor Remainder Quotient/Dividend Divisor Remainder indicator targets Quotient/Dividend Divisor Remainder Indicator targets D74 Quotient/Dividend Divisor Remainder Branch targets 1 F74 Quotient/Dividend Divisor Remainder Branch targets Indicator Branch options Branch options Operand 1 2 options DIVREMBS 1 scalar. Operand 3 Remainder 1374 DIVREMIS Operand number, or absolute instruction Quotient/Dividend Divisor DIVREMSR 1 relative instruction Form - Numeric variable scalar or character variable 1174 DIVREMISR ' 1: Numeric variable Operand [4-61J scalar. Chapter 2. Computation and Branching Instructions 2-150 Divide with Operand 2: Numeric Operand 3: Numeric variable Operand 4-6 . . scalar. Branch Form - Branch number. indicator Remainder (DIVREM) scalar. point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. The Quotient is the result of dividing the Dividend by the Dividend minus the product of the Divisor and Quotient. Description: Divisor. Operands can have packed or zoned decimal, signed or unsigned binary The Remainder is the type. operands are the Quotient and Source operands are the Dividend and Divisor. The receiver Remainder. If according to the following rules: operands are not of the same type, source operands are converted to or packed decimal type, source operands are converted 1. If any one of the operands has zoned packed decimal. 2. Otherwise, the binary operands are converted to a logically treated as signed binary(4) scalars. like type. Note: unsigned binary(2) scalars are decimal operands are divided using Source operands are divided according to their type. Packed unsigned source operands. Signed with used is division packed decimal division. Unsigned binary division. binary binary operands are divided using two's complement Better performance can be obtained division execute faster than Floating-point is if all operands have the same packed decimal type. Signed and unsigned binary division. not supported for this instruction. divide (hex 0C0B) exception is signaled. If the the divisor operand has a numeric value of 0, a zero is a zero value quotient and remainder. dividend operand has a value of 0, the result of the division If divide operation is determined by the For a decimal operation, the precision of the result of the words, the divide operation will number of fractional digit positions specified for the quotient. In other same precision as that specified for the be performed so as to calculate a resultant quotient of the assumed decimal point for the dividend and quotient operand. If necessary, internal alignment of the value. These performed to ensure the correct precision for the resultant quotient divisor operands is decimal point alignment exception. An internal internal alignments are not subject to detection of the decimal attributes which may be specified for quotient value will be calculated for any combination of the result to the quotient operand is subject to the instruction's operands. However, the assignment of to, at most, the rightmost 31 digits of detection of the size exception thereby limiting the assignment the calculated result. If the dividend operand is shorter than the divisor operand, it is logically adjusted to the length of the divisor operand. The division operation is performed according to the rules of algebra. Unsigned binary is treated as a result of the operation is copied into the quotient that used in performing the operation, the resultant as type operand If this operand is not the same value is adjusted to the length of the quotient resultant the value is converted to its type. If necessary, operand, or both before being copied to quotient the operand, aligned at the assumed decimal point of positive number for the algebra. The quotient Chapter 2. Computation and Branching Instructions 2-151 Divide with is significant digits are truncated If it. on the signaled. ~ ft meriC Va Ue q ' ca |culaL affollows Remainder = Dividend ^ left Remainder (DIVREM) end of the resultant value a size (hex OCOA) exception be6 " determined the numeric value of the remainder operand ' is (Quotient*Di visor) - ™ po “ n,f ,0 of,his ins *ruction is being used, the rounding applies to the quotient but not the remainder. The quotient value used to calculate the remainder is the resultant value of the diviSIOn 6 resu,tant value of the calculation is copied into the remainder operand. The siqn of the remainder is the same as that of the dividend operand unless the remainder has a value of 0 in which case its sign is positive. If the remainder operand is not the same type as that used in performing the operahon, the resultant value is converted to its type. If necessary, the resultant value is adjusted to 9 h f th remainde °P erand aligned at the assumed decimal point of the remainder operand, nrr hnth f° K both h before being copied to it. If significant digits are truncated off the left end of the resultant value, a size (hex OCOA) exception is signaled. ' . . '' ' a decimal to binary conversion causes a size (hex OCOA) exception to be signaled (in programs that equest size exceptions to be signaled), the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. If Resultant Conditions: • positive • negative • zero The algebraic value of the numeric scalar quotient is Exceptions Operands Exception 06 01 Spacing addressing violation 02 Boundary alignment 03 Range 06 Optimized addressability invalid 08 2 3 4 X X X X X X X X X X X X X X X X X X X X X X Parameter reference violation Computation 02 Decimal data 0A Size X < 0B Zero divide 10 X Damage encountered 04 System object 44 1C Partial damage state system object damage < X X X X C X X X X Machine-dependent exception 03 Machine storage 20 Other Argument/parameter 01 0C 1 Addressing limit exceeded X Machine support Chapter 2 . Computation and Branching Instructions 2-152 Divide with Remainder (DIVREM) Operands 1 Exception 02 Machine check 2 3 4 X X 03 Function check 22 Other Object access X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 Object not found 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2C Program execution X 04 Invalid branch target 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-153 Edit (EDIT) Op Code (Hex) 10E3 Operand Operand 1 Receiver Operand 3 Edit Mask 2 Source Operand /: Operand 2: Numeric scalar or data-pointer-defined numeric Operand 3: Character variable scalar or data-pointer-defined character scalar. Character variable scalar or data-pointer-defined character scalar. scalar. ILE access LBEDIT ( var receiver var receiverjength var source : : : var source_attributes var mask var mask length EDITPD : aggregate ; unsigned binary, signed binary, OR unsigned binary, OR packed decimal aggregate-, aggregate-, unsigned binary ( var receiver receiverjength var source sourcejength var mask maskjength : : aggregate ; unsigned binary, packed decimal-, unsigned binary, aggregate-, unsigned binary The value of a numeric scalar suitable for display at a source/sink device. Description: is transformed from its The following general internal form to character editing functions can be form performed during transforming of the source operand to the receiver operand: • Unconditional insertion of a source value digit with a zone as a function of the source value's algebraic sign • Unconditional insertion of a • Conditional insertion of one of two possible source value's algebraic sign mask operand character string mask operand character Conditional insertion of a source value digit or a source value leading zero suppression strings as a function of the mask operand replacement character as a function of • Conditional insertion of either a mask operand character string or a series of replacement characters as a function of source value leading zero suppression Conditional floating insertion of one of two possible mask operand character strings as a function of both the algebraic sign of the source value and leading zero suppression The operation is performed by transforming the source (operand (operand 3) and placing the result in the receiver (operand 1). Chapter 2. 2) under control of the edit mask Computation and Branching Instructions 2-154 Edit (EDIT) The mask operand (operand 3) is limited to no more than 256 bytes. contains both The source field is converted to packed decimal format. The edit mask are processed fields source edit mask and the control character and data character strings. Both the of digits in number placed in the result field from left to right. If the left to right, and the edited result is for checked field are ignored and not the source field is even, the four high-order bits of the source (hex for validity, and a decimal data All other source digits as well as the sign are checked Mask Syntax: validity. 0C02) exception is signaled when one is invalid. Overlapping of any of these fields gives unpredictable results. through hex AD and hex AF Nine fixed value control characters can be in the edit mask, hex AA characters to be inserted into the through hex B3. Four of these control characters specify strings of that a digit from the source field should result field under certain conditions; and the other five indicate taken. be checked and the appropriate action control character indicates the end variable value control character can be in the edit mask. This can vary with each execution of the of a string of characters. The value of the end-of-string character the edit mask. If the first character in character first the value of instruction and is determined by the as the end-of-string character. If used is value that then of the edit mask is a value less than hex 40, hex 40, then hex AE is used as than greater to or equal the first character of the edit mask is a value One the end-of-string character. It remains set to the off state at the start of the execution of this instruction. four of the one until field or source the in encountered in this state until a nonzero source digit is in the encountered is (hex B3) string unconditional an unconditional digits (hex AA through hex AD) or A significance indicator edit is mask. When before significance (to the is left of) detected, the selected floating string the first significant result character. is overlaid into the result field immediately result character has been the significance indicator is set to the on state, the first significant fill character or a digit from the whether determines indicator reached. The state of the significance digits and characters in conditional the source field is to be inserted into the result field for conditional until it is replaced by the first 40 hex is a character strings specified in the edit mask field. The fill B1). (hex character control character following the floating string specification When When • A the significance indicator is in the off state: conditional digit control character in the edit mask causes the fill character to be moved to the result field. • A character in a conditional string in the edit mask causes the fill character to be moved to the result field. When » A the significance indicator is in the on state: conditional digit control character in the edit mask causes a source digit to be moved to the result field. • A character in a conditional string in the edit The following control characters are found in mask the edit is moved mask to the result field. field. less than hex 40 or hex AE) indiEnd-of-String Character One of these control characters (a value is null. cates the end of a character string and must be present even if the string Static Field Character: Chapter 2. Computation and Branching Instructions 2-155 Edit (EDIT) Hex AF This control character indicates the start of a static field. of two mask character strings immediately following one A used to indicate that static field is character is to be inserted into the result held, depending upon the algebraic sign of the source field. If the sign is positive the first string is to be inserted into the result field; if the sign is negative, the second strinq’is this be inserted. to Static field format: <Hex AF> <positive string>. . ,<less than hex 40> <negative string>. . ,<hex AE> OR <HexAF> < positive string >.. ,<hex AE> < negative string >...< hex AE> Floating String Specification Field Character: Hex B1 This control character indicates the start of a floating string specification field. The first character of the field is used as the fill character; following the fill character are two strings delimited by the end-of-string control character. If the algebraic sign of the source field is positive the first string is to be overlaid into the result field; if the sign is negative, the second string is to be overlaid. The string selected to be overlaid into the result field, called a floating string, left of the first significant result character. If diately to the string is significance placed in the result is appears immenever set neither field. Conditional source digit positions (hex B2 control characters) must be provided in the edit mask immediately following the hex B1 field to accommodate the longer of the two floating strings; otherwise, a length conformance exception is signaled. For each of these B2 strings, the fill character is inserted into the result field, and source digits are not consumed. This ensures that the floating string never overlays bytes preceding the receiver operand. Floating string specification field format: <HexB1> string >. . <fill character> < positive .< end-of-string character> string >.. . < end-of-string character > cnegative followed by <Hex B2>. . . Conditional String Character: Hex BO This control character indicates the start of a conditional string, which consists of any characters delimited by the end-of-string control character. Depending on the state of the significance indicator, this string or fill characters replacing it is inserted into the result field. If the significance indicator is off, a fill character for every character in the conditional string is placed in the result field. If the indicator is on, the characters in the conditional string are placed in the result field. Conditional string format: <Hex B0> < conditional string >. . .< end-of-string character Unconditional String Character: Hex B3 This control character turns on the significance indicator and indicates the start of an uncondiany characters delimited by the end-of-string control character This string is unconditionally inserted into the result field regardless of the state of the significance indicator. If the indicator is off when a B3 control character is encountered the appropriate floating string is overlaid into the result field before (to the left of) the B3 unconditional string (or to the left of where the unconditional string would have been if it were not null). tional string that consists of Unconditional string format: Chapter 2 . Computshon and Branching Instructions 2-156 Edit (EDIT) < unconditional < Hex B3> string >. . . <end-of-string character Control Characters That Correspond to Digits in the Source Field: This control character specifies that either the corresponding source field digit or the floating string (hex B1) fill character is inserted into the result field, depending on the state of the significance indicator. If the significance indicator is off, the fill character is placed in the Hex B2 result field; the result if the indicator is on, the source digit the zone supplied field, detected, the floating string is is is hex F. When overlaid to the placed. is When a source digit significance (that left of the first is moved a nonzero source is, to digit) significant character. Control characters hex AA, hex AB, hex AC, and hex AD turn on the significance indicator. If the indicator is off when one of these control characters is encountered, the appropriate floating string is overlaid into the result Hex AA This before (to the field left of) the result digit. control character specifies that the corresponding source field digit is unconditionally in the 4 low-order bits of the result field with the zone set to a hex F. placed Hex AB This control character specifies that the corresponding source field digit placed in the result digit is set to hex D to hex field. If the sign of the source F (the preferred positive sign); if field is is unconditionally positive, the zoned portion of the the sign is negative, the zone portion is set (the preferred negative sign). control character specifies that the corresponding source field digit is unconditionally placed in the result field. If the algebraic sign of the source field is positive, the zone portion Hex AC This of the result moved Hex AD This is set to hex F (the preferred positive sign); otherwise, the source sign field to the result zone is field. control character specifies that the corresponding source field digit is unconditionally set in the result field. If the algebraic sign of the source field is negative, the zone is placed (the preferred negative sign); otherwise, the hex D to source field sign is moved to the zone position of the result byte. The following table provides an overview of the results obtained with the valid edit conditions and sequences. Table 2-1 (Page 1 of 3). Valid Edit Conditions and Results Resulting Previous Mask Significance Source Source Result Significance Character indicator Digit Sign Character(s) indicator AF Off/On Any Positive Positive string No Change inserted Off/On Any No Change Negative string Negative inserted AA Off 0-9 string overlaid; F, Off 0-9 On Positive floating Positive source hex digit Negative floating hex Negative On string overlaid; F, AB On 0-9 Any Off 0-9 Positive source Hex F, digit source digit F, Off 0-9 On Positive floating string overlaid; source hex digit Negative floating hex Negative On On string overlaid; D, Chapter 2. source digit Computation and Branching Instructions 2-157 Edit (EDIT) Table 2-1 (Page 2 of 3). Valid Edit Conditions and Results Previous Resulting Mask Significance Source Source Result Character Significance Indicator Digit Sign Character(s) Indicator On 0-9 Positive Hex F, source digit On On 0-9 Negative Hex D, source digit On Off 0-9 Positive AC Positive floating string overlaid; F, Off 0-9 Negative source hex digit Negative floating On string overlaid; source sign and AD On 0-9 Positive Hex On 0-9 Negative Source sign and Off 0-9 Positive F, source digit digit digit On On On Positive floating string overlaid; source sign and BO Off 0-9 On digit Negative Negative floating string overlaid; hex D, source digit On 0-9 Positive Source sign and On On 0-9 Negative Hex Off Any Any Insert for digit On character Off source D, fill digit each B0 string character On Any Any B0 character Insert On string B1 (including Off Any Any Insert the necessary B2s) fill char- No Change acter for each B2 character that corresponds acter to a char- the longer of the two floating in strings B2 (not for a B1 Off 0 Any 1-9 Positive Insert fill character Off field) Off Overlay positive and insert hex F, source On floating string digit Off 1-9 On 0-9 Any Hex Off Any Positive Overlay positive floating string and insert B3 character Negative Overlay negative floating string and insert hex F, source On digit B3 F, source digit On string Chapter 2 . Computation and Branching Instructions 2-158 Edit (EDIT) Table 2-1 Mask Character (Page 3 of 3). Valid Edit Conditions and Results Previous Source Source Significance Sign Digit Indicator Any Off Resulting Significance Result Character(s) Indicator Overlay negative Negative floating string insert On and B3 character string Any Any On Insert B3 character On string Note: 1. Any character 2. Hex AF, hex is a valid B1, hex BO, character, including the end-of-string character. fill and hex B3 strings must be terminated by the end-of-string character even if they are null strings. 3. 4. a hex B1 field has not been encountered (specified) when the significance indicator is turned on, the floating string is considered to be a null string and is therefore not used to overlay into the result field. unequal length, additional static fields are necessary If the positive and negative strings of a static field are of If ensure that the sum of the lengths of the positive strings equal the sum of the lengths of the negative length does not strings; otherwise, a length conformance (0C08) exception is signaled because the receiver correspond to the length implied by the edit mask and source field sign. to The following figure indicates the valid ordering of control characters in an edit AA, AB, AC, mask field. AD Control Character Y AF BO B1 B2 B3 0 0 2 2 2 0 AF 0 0 0 0 0 0 BO 1 0 0 2 0 1 1 0 1 3 1 1 B2 1 0 0 2 0 1 B3 0 0 2 2 2 0 Control Character X AAC011-0 Explanation: Condition Definition 0 Both X and Y can appear in the edit mask field in either order. 2 Y cannot precede X cannot precede 3 Both control characters (two Bl's) cannot appear 1 Violation of Figure X. Y. any of the above rules 2-6. Edit Mask will result in in an edit mask field. an edit mask syntax (hex 0C05) exception. Field Control Characters Chapter 2, Computation and Branching Instructions 2*1 59 Edit (EDIT) The following steps are performed when the - The numeric value before the editing diate packed field Binary(2) Binary(4) • = = the source operand is converted to a packed decimal intermediate value done. If the source operand is binary, then the attributes of the intermebefore the edit are calculated as follows: in packed packed Insert Floating String into - If Edit Digit a floating string or (5,0) (10,0) digits in the edit The end of the • Edit is mask and mask insertion characters to be inserted into the receiver operand into the receiver field, this is edit digit count (hex OC04) exception field is is done after the other editing. signaled when: reached and there are more control characters that correspond field is reached and there are more digit positions in the source Mask Syntax Exception: An edit mask syntax (hex 0C05) exception is signaled when an mask control character is encountered or when a sequence rule is violated. Length Conformance Exception: The end of the edit The end of the result field mask A length conformance (hex 0C08) exception field is is The following are is to reached and more positions remain field limits that in the edit field. invalid signaled when: reached and there are more character positions The number of B2s following a B1 Limitations: is field. mask edit digits Receiver Field Count Exception: An The end of the source • • done: Edit • • is is The editing of the source done from left to right. edit editing Convert Source Value to Packed Decimal • mask the result in field. field. cannot accommodate the longer of the two floating strings. apply to the functions performed by this instruction. Exceptions Operands Exception 1 06 Addressing 01 03 Range 04 External data object not found 06 Optimized addressability invalid Argument/parameter 01 0C 3 Other XXX XXX XXX XXX XXX XXX Spacing addressing violation 02 Boundary alignment 08 2 Parameter reference violation Computation 02 Decimal data X 04 Edit X digit count 05 Edit mask syntax X 08 Length conformance X Chapter 2. Computation and Branching Instructions 2-160 Edit (EDIT) Operands Exception 10 Damage encountered damage 04 System object 44 1C Partial system object damage 22 limit X X X X X X X 02 Machine check X 03 Function check X XXX XXX XXX XXX XXX Object access Object not found 08 object compressed Pointer specification 01 Pointer does not exist 02 Pointer type invalid Resource control limit 01 user profile storage limit X exceeded Scalar specification 01 X Scalar type invalid X X X 02 Scalar attributes invalid 36 X X 03 Object suspended 32 Other exceeded 02 Object destroyed 2E 3 Machine support 01 24 2 Machine-dependent exception 03 Machine storage 20 state 1 Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-161 Exchange Bytes (EXCHBY) Exchange Bytes (EXCHBY) Op Code (Hex) Operand Source 1 1°CE Operand 2 Source 2 1 Operand 1: Character variable scalar (fixed-length) or numeric variable scalar. Operand 2: Character variable scalar (fixed-length) or numeric variable scalar. The logical character string values of the two source operands are exchanged. The value of the second source operand is placed in the first source operand and the value of the first source operand is placed in the second operand. Description: The operands can be either character or numeric. Any numeric operands are interpreted as character strings. Both operands must have the same length. logical Exceptions Operands Exception 06 01 08 Spacing addressing violation X X X X 03 Range X X 06 Optimized addressability invalid X X X X Parameter reference violation Damage encountered 44 Partial XXX XXX system object damage Machine-dependent exception 03 Machine storage 20 limit exceeded Machine support 02 Machine check X 03 Function check 22 Other Argument/parameter 04 System object damage state 1C 2 02 Boundary alignment 01 10 1 Addressing X Object access Object not found X X 02 Object destroyed X X 03 Object suspended X X X X X x 01 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control limit 01 user profile storage limit exceeded X Chapter 2 . Computation and Branching Instructions 2-162 Exchange Bytes (EXCHBY) Operands Exception 36 1 2 Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-1 63 Or (XOR) Exclusive Exclusive Or (XOR) Op Code XOR (Hex) Extender Operand Operand 2 Operand Receiver Source 1 Source 2 Receiver Source 1 Source 2 Indicator targets Receiver Source 1 Source 2 Branch targets 1 Operand 3 [4-5] 109B XORI Indicator 189B options XORB Branch options 1C9B Operand 1: Operand 2: Character scalar or numeric scalar. Operand 3: Character scalar or numeric scalar. Operand 4-5: Character variable scalar or numeric variable scalar. Branch Form-Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code (Hex) Extender Operand XORS 1 Operand 2 1 Operand 1 Source 2 Indicator options Receiver/Source 1 Source 2 Indicator targets Branch options Receiver/Source 1 Source 2 Branch targets 19B XORIS 199B XORBS 1 [3-4] Receiver/Source D9B Operand 1: Operand 2: Character variable scalar or numeric variable scalar. Character scalar or numeric scalar. Operand 3-4 Branch Form- Branch number. • point, instruction pointer, relative instruction number, or absolute instruction Indicator Form- Numeric variable scalar or character variable scalar. Description: The Boolean EXCLUSIVE operands. The resulting string is OR placed in operation is performed on the string values in the source the receiver operand, The operands may be character or numeric scalars. They are both interpreted as stringing is supported for both character and numeric operands. bit strings. Sub- The length of the operation is equal to the length of the longer of the two source operands. The shorter of the two operands is padded on the right. The operation begins with the two source operands left-adjusted and continues bit by bit until they are completed. Chapter 2. Computation and Branching Instructions 2-1 64 Exclusive Or (XOR) The values of the result are determined as follows: bit Source Source 2 Bit 1 Result Bit Bit 0 0 0 0 1 1 1 0 1 1 1 0 The result value place on the is then placed (left-adjusted) in the receiver operand with truncating or padding taking right. The pad value used in this instruction is a hex 00. Substring operand references that allow for a null substring reference (a length value of zero) may be and 3. The effect of specifying a null substring reference for one source operand is that the other source operand is EXCLUSIVE ORed with an equal length string of all hex 00s. When a null substring reference is specified for both source operands, the result is all zero and specified for operands 1, 2, the instruction's resultant condition receiver, a result is is zero. When a null substring reference not set and the instruction's resultant condition is is specified for the zero regardless of the values of the source operands. If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. When is a numeric variable scalar, it is possible that the result produced will not numeric type. This can occur due to padding with hex 00, due to truncation, or string produced by the instruction. The instruction completes normally and the receiver operand be a valid value for the due to the resultant bit signals no exceptions for these conditions. Resultant Conditions • Zero-The reference • value for the bit is bits of the scalar receiver operand is either all zero or a null substring specified for the receiver. Not zero-The bit value for the bits of the scalar receiver operand is not all zero. Exceptions Operands 1 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 10 Other parameter reference violation Damage encountered 04 system object damage state Chapter 2. X Computation and Branching Instructions 2-165 Exclusive Or (XOR) Operands Exception 44 1C partial system object damage 22 limit Machine support 02 machine check X 03 function check X Object access XXX XXX XXX XXX XXX 03 object suspended 08 object compressed Pointer specification 01 pointer does not exist 02 pointer type invalid Program execution 04 invalid branch target 2E Resource control X limit 01 user profile storage limit 36 Other X X 02 object destroyed 2C 3 X exceeded 01 object not found 24 2 X Machine-dependent exception 03 machine storage 20 1 X exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-166 Extended Character Scan (ECSCAN) Extended Character Scan (ECSCAN) Op Code Operand Extender Operand 1 Operand 2 Operand 4 3 Operand [5-7] (Hex) ECSCAN Base Receiver 10D4 ECSCANB Branch 1CD4 options Base Receiver ECSCANI Indicator 18D4 options Base Receiver Operand 1: Binary variable scalar or binary array. Operand 2: Character variable scalar. Operand 3: Character scalar. Operands. Character(l) Operand Compare Mode operand operand Compare Mode Branch operand operand targets Compare Mode Indicator operand operand targets scalar. 5-7: 3 Branch Form - Branch number, * Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Description: This instruction scans the string value of the base operand for occurrences of the string value of the compare operand and indicates the relative locations of these occurrences in the receiver operand. The character string value of the base operand is scanned for occurrences of the character compare operand under string value of the embedded in the base control of the mode operand and mode control characters string. The base and compare operands must both be character strings. The length of the compare operand must not be greater than that of the base string. The base and compare operand are interpreted as containing a mixture of 1-byte (simple) and 2-byte (extended) character codes. The mode, simple or extended, with which the string is to be interpreted, is controlled initially by the mode operand and thereafter by mode control characters embedded in the strings. The mode control characters are as follows: = • Hex OE • Hex OF = Shift out of Shift into in The format • the first of the simple character simple character mode to extended mode. mode from extended mode. 0 mode operand 1 - Operand 0 1 - if it occurs is as follows: mode Bit 0 indicator mode. extended character mode. starts in simple character starts in 3 initial = Operand = Operand recognized only Char(1) 2 initial = Operand = Operand is byte position of an extended character code. Mode operand - Operand This mode indicator starts in simple character starts in Reserved (binary Bit 1 mode. extended character mode. Bits 2-7 0) Chapter 2. Computation and Branching Instructions 2-1 67 Extended Character Scan (ECSCAN) The operation begins at the left end of the base string and continues character by character, left to simple character mode, the operation moves through the base string 1 byte at a time. When the base string is interpreted in extended character mode, the operation moves through the base string 2 bytes at a time. When right. the base string is interpreted in The compare operand value is the entire byte string specified for the compare operand. The mode operand determines the initial mode of the compare operand. The first character of the compare operand value is assumed to be a valid character for the initial mode of the compare operand and not mode control character. Mode control characters in the compare operand value participate in comparisons performed during the scan function except that a mode control character as the first character of the compare operand causes unpredictable results. a is scanned until the mode of the characters being processed is the same as the initial compare operand value. The operation continues comparing the characters of the base string with those of the compare operand value. The starting character of the characters being compared in the base string is always a valid character for the initial mode of the compare operand value. A mode control character encountered in the base string that changed the base string mode to match the initial mode of the compare operand value does not participate in the comparison. The length of the comparison is equal to the length of the compare operand value and the comparison is performed the same as performed by the Compare Bytes Left Adjusted instruction. The base mode If string of the If the receiver operand base is a scalar, only the found, the binary value for the relative an array, as mode change is encountered the characters being processed first is placed in the receiver operand. occurrence of the compare operand is noted. If the there are elements in the array are noted. many occurrences as is a is string character of the set of bytes receiver operand If compare operand value a set of bytes that matches the location of the leftmost the base string, the base string is again scanned until the mode of the same as the initial mode of the compare operand value, and in is then the comparisons are resumed. The operation continues until no more occurrences of the compare operand value can be noted in the receiver operand or until the number of bytes remaining to be scanned in the base string is less than the length of the compare operand value. When the second condition occurs, the receiver value is set to zero. If the receiver operand is an array, all its remaining elements are also set to zero. If the escape code encountered result condition is specified (through a branch or indicator option), verperformed on the base string as it is scanned. Each byte of the base string is checked a value less than hex 40. When a value less than hex 40 is encountered, it is then determined if it ifications are for is a valid mode control character. If a byte value of less than hex 40 is not a valid mode control character, it is considered to be an escape code. The binary value for the relative location of the character (simple or extended) being interrogated is placed in the receiver operand, and the appropriate action (indicator or branch) is performed according to the specification of the escape code encountered result condition. If the receiver operand is an array, the next array element after any elements set with locations or prior occurrences of the compare operand, is set with the location of the character containing the escape code and all the remaining array elements are set to zero. If the escape encountered result condition base is not specified, verifications of the character codes in the string are not performed. Chapter 2. Computation and Branching Instructions 2-1 68 Extended Character Scan (ECSCAN) Resultant Conditions • Positive-The numeric value(s) of the receiver operand • Zero-The numeric value(s) of the receiver operand is zero. In the case where the receiver operand is an array, the resultant condition is zero if all elements are zero. • is positive. Escape code encountered-An escape character code value was encountered during the scanning of the base string. Exceptions Operands Exception 06 1 2 3 4 space addressing violation X X X X 02 boundary alignment violation X X X X 03 range X X X X 06 optimized addressability invalid X X X X X X X X Addressing 01 08 Argument/parameter 01 0C parameter reference violation XXX Computation 08 length conformance 10 Damage encountered X 04 System object damage state 44 1C partial 22 X system object damage Machine-dependent exception 03 machine storage 20 Other limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X X X 02 object destroyed X X X X 03 object suspended X X X X X X X X X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification Chapter 2. Computation and Branching Instructions 2-169 Extended Character Scan (ECSCAN) Operands Exception 01 scalar type invalid 03 scalar value invalid 36 1 2 4 X X X Other X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-170 Extract Exponent (EXTREXP) Extract Exponent (EXTREXP) Op Code (Hex) EXTREXP Extender Operand 2 Source Operand Receiver Branch options Receiver Source Branch targets Indicator options Receiver Source Indicator targets Operand 1 [3-6] 1072 EXTREXPB 1C72 EXTREXPI 1872 Operand 1: Binary variable scalar. Operand 2: Floating-point scalar. Operand 3-6: • Branch Form- Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Description: This instruction extracts the exponent portion of a floating-point scalar source operand and places into the receiver it operand as a binary variable scalar. The operands must be the numeric types indicated because no conversions are performed. The source floating-point field and either a signed exponent, placed in interrogated to determine the binary floating-point value represented is for number values, or a special identifier, for infinity and NaN values, is the binary variable scalar receiver operand. The value to be assigned to the receiver, is dependent upon the floating-point value represented in the source operand as described below. It is a signed binary integer value and a numeric assignment of the value When is made to the receiver. the source represents a normalized number, the biased exponent contained of the source is in the exponent field converted to the corresponding signed exponent by subtracting the bias of 127 for short or 1023 for long to determine the value to be returned. The + 127 the receiver +1023 When resulting value ranges from -126 to is unsigned binary, a negaexponent will result in a size (hex 0C0A) exception unless size exceptions are suppressed by using the suppress binary size exception program attribute on the Create Program (CRTPG) instruction. for short format, -1022 to for long format. tive When the source represents a denormalized number, the value to be returned adjusting the signed exponent of the denormalized number. number is is determined by The signed exponent of a denormalized a fixed value of -126 for the short format and -1022 for the long format. value the signed exponent would be if the source value was adjusted It adjusted to the is to a normalized number. The resulting value ranges from -127 to -149 for short format, -1023 to -1074 for long format. When the source represents a value of zero, the value returned When the source represents When the source represents a not-a-number, the value returned infinity, the value returned For an unsigned binary(2) a value of 32768 4294934528 is is is is zero. +32767. is -32768 for a signed binary receiver. returned, and for a unsigned binary(4) a value of returned. Chapter 2. Computation and Branching Instructions 2-1 71 Extract Exponent (EXTREXP) Resultant Conditions • Normalized-The source operand value represents a normalized binary floating-point number. The signed exponent • is stored in Denormalized-The source operand value represents a denormalized binary floating-point number. An adjusted signed exponent • • the receiver. Infinity-The is stored in the receiver. source operand value represents infinity. The receiver is set with a value of +32767. NaN-The source operand value represents a not-a-number. The receiver when signed binary, 4294934528 when unsigned -32768 with a value of 32768 when unsigned is binary(2), set with a value of and with a value of binary{4). Exceptions Operands Exception 06 1 2 space addressing violation X X 02 boundary alignment violation X X 03 range X X 06 optimized addressability invalid X X X X 01 08 Argument/parameter 01 10 parameter reference violation Damage encountered 04 System object damage state 44 1C partial 22 X system object damage X Machine-dependent exception 03 machine storage 20 Other Addressing limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 X exceeded X Scalar specification Chapter 2. Computation and Branching Instructions 2-1 72 Extract Exponent (EXTREXP) Operands Exception 01 scalar type invalid 36 1 2 X X Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-1 73 Extract Magnitude Magnitude (EXTRMAG) Extract Op Code (EXTRMAG) (Hex) Extender Operand Operand 2 Source Operand Receiver Indicator options Receiver Source Indicator targets Branch options Receiver Source Branch targets EXTRMAG 1 [3-6] 1052 EXTRMAGI 1852 EXTRMAGB 1C52 Operand 1: Numeric variable Operand 2: Numeric Operand 3-6 scalar. scalar. • Branch Form- Branch number. • Indicator Form- Numeric variable scalar or character variable scalar. point, instruction pointer, relative instruction number, or absolute instruction Short forms Op Code (Hex) Operand Extender EXTRMAGS Operand 1 [2-5] Receiver/Source 1152 EXTRMAGIS Indicator options Receiver/Source Indicator targets Branch options Receiver/Source Branch targets 1952 EXTRMAGBS 1 D52 Operand Operand 1: Numeric variable scalar. 2-5: • Branch Form- Branch number. • Indicator Form- Numeric variable scalar or character variable scalar. point, instruction pointer, relative instruction Description: The numeric value of the source operand the numeric variable scalar receiver operand. The absolute value • its absolute value and placed in follows: Extract the numeric value and form twos complement if the source operand is negative. Unsigned signed binary • formed from the source operand as converted to Signed binary • is is number, or absolute instruction Extract the numeric value. Packed/Zoned - Extract the numeric value and force the source operand's sign to positive. Chapter 2, Computation and Branching Instructions 2-174 Extract Magnitude • (EXTRMAG) Floating-point — Extract the numeric value and force the significand sign to positive. copied into the receiver operand according to the rules of the Copy If this operand is not the same type as that used in performing the operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the length of the receiver operand, or aligned at the assumed decimal point of the receiver operand, or The result of the operation Numeric Value instruction. is both before being copied to size (hex OCOA) exception is it. If binary value to a binary scalar of the When on the left end of the resultant value, a magnitude of a maximum negative a size (hex OCOA) exception. significant digits are truncated An attempt signaled. same to extract the size also results in the source floating-point operand represents not-a-number, the sign field of the source forced to positive and this value not altered is in is not the receiver. a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfracIf tional digits. For a fixed-point operation, if significant digits are truncated from the left end of the resultant value, a size (hex OCOA) exception is signaled. An attempt to extract the absolute value of a maximum negative binary value into a binary scalar of the same size also results in a size (hex OCOA) exception. For floating-point operations that involve a fixed-point receiver field, if nonzero digits would be truncated from the left end of the resultant value, an invalid floating-point conversion (OCOC) exception is signaled. For a floating-point receiver operand, if the exponent of the resultant value is either too large or too small to be represented in the receiver field, the floating-point overflow (hex 0C06) or the floating-point underflow (hex 0C07) exception is signaled. Resultant Conditions • Positive-The algebraic value of the receiver operand • Zero-The algebraic value of the receiver operand • Unordered-The value assigned a floating-point receiver operand is is positive. zero. is NaN. Exceptions Operands 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 OC Other parameter reference violation Computation X 02 decimal data 06 floating-point overflow X 07 floating-point underflow X Chapter 2. Computation and Branching Instructions 2-175 Extract Magnitude (EXTRMAG) Operands Exception 09 floating-point invalid operand 10 size X 0C invalid floating point conversion X 0D floating-point inexact result X damage partial X X X system object damage X X X Machine-dependent exception 03 machine storage 22 limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Resource control X X X X limit 01 user profile storage limit 36 X Program execution 04 invalid branch target 2E Other Damage encountered 44 20 2 X OA 04 system object 1C 1 exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-176 Multiply (MULT) (MULT) Multiply Op Code Operand Operand 2 Operand Product Multiplicand Multiplier Product Multiplicand Multiplier Product Multiplicand Multiplier Indicator targets Product Multiplicand Multiplier Indicator targets Operand Extender (Hex) MULT 1 3 [4-7] 104B MULTR 124B MULTI Indicator 184B options MULTIR 1A4B options MULTB Branch options Product Multiplicand Multiplier Branch targets Branch options Product Multiplicand Multiplier Branch targets Indicator 1C4B MULTBR E4B 1 Numeric variable Operand 1 Operand 2: Numeric scalar. Operand 3: Numeric scalar. Operand 4-7: • • : Branch Form - Branch number. scalar. point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable Indicator number, or absolute instruction scalar. Short forms Op Code MULTS (Hex) Operand Extender Operand 1 2 Operand [3-6] Product/Multiplicand Multiplier Product/Multiplicand Multiplier Indicator options Product/Multiplicand Multiplier Indicator targets MULTISR B4B Indicator options Product/Multiplicand Multiplier Indicator targets MULTBS Branch options Product/Multiplicand Multiplier Branch targets Branch options Product/Multiplicand Multiplier Branch targets 104B MULTSR 134B MULTIS 194B 1 1 D4B MULTBSR 1 F4B Operand 1: Numeric variable scalar. Chapter 2. Computation and Branching Instructions 2-177 Multiply Operand 2: Operand 3-6: Numeric scalar. * Branch Form-Branch number. • Indicator Description: point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable The Product Operands can have is number, or absolute instruction scalar. the result of multiplying the Multiplicand and the Multiplier. floating-point, packed or zoned decimal, signed or unsigned binary type. Source operands are the Multiplicand and The receiver operand Multiplier. is the Product. operands are not of the same type, source operands are converted according If 1. If (MULT) any one of the operands has floating point type, to the following rules: source operands are converted to floating point type. 2. Otherwise, if any one of the operands has zoned or packed decimal type, source operands are converted to packed decimal. 3. Otherwise, the binary operands are converted to a logically treated as signed binary(4) scalars. unsigned binary(2) scalars are like type. Note: Source operands are multiplied according to their type. Floating point operands are multiplied using Packed decimal operands are multiplied using packed decimal multiplication. Unsigned binary multiplication is used with unsigned source operands. Signed binary operands are multiplied using two's complement binary multiplication. floating point multiplication. Better performance can be obtained if Decimal operands used If in operands have the same type. Signed and unsigned binary packed decimal or floating point multiplication. all multiplication execute faster than either floating-point operations cannot contain the multiplicand operand or the multiplier operand has a value of more than 0, 15 total digit positions. the result of the multiplication is a zero product. For a decimal operation, no alignment of the assumed decimal point is performed for the multiplier and multiplicand operands. The operation occurs using the specified lengths of the multiplicand and logical zero padding on the left multiplier operands with no necessary. Floating-point multiplication uses exponent addition and significand multiplication. For nonfloating-point computations and for significand multiplication for floating-point operations, the multiplication operation is performed according to the rules of algebra. Unsigned binary operands are treated as positive numbers for the algebra. The result of the operation is copied into the product operand. If this operand is not the same type as performing the operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the length of the product operand, aligned at the assumed decimal point that used in of the product operand, or both before being copied to it. For the optional round form of the instruction, specification of a floating-point receiver operand is invalid. Chapter 2. Computation and Branching Instructions 2-178 (MULT) Multiply For fixed-point operations in programs that request to be notified of size exceptions, if nonzero digits are truncated from the left end of the resultant value, a size (hex OCOA) exception is signaled. For floating-point operations involving a fixed-point receiver field (if nonzero digits would be truncated from the left end of the resultant value), an invalid floating-point conversion (hex OCOC) exception is signaled. For a floating-point product operand, if the exponent of the resultant value is either too large or too small to be represented in the product field, the floating-point overflow (hex 0C06) or the floating-point underflow (hex 0C07) exception is signaled. performed on these If operands overlap but do not share all of the same bytes, results of operations operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. If a decimal to binary conversion causes a size (hex OCOA) exception to be signaled, the binary value if the decimal value contains 15 or fewer significant nonfrac- contains the correct truncated result only tional digits. Resultant Conditions • Positive-The algebraic value of the numeric scalar product • Negative-The algebraic value of the numeric scalar product ® Zero-The algebraic value of the numeric scalar product 9 Unordered-The value assigned a floating-point product operand is is is positive. negative. zero. is NaN. Exceptions Operands 06 2 3 [4, 5] X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X X X X X X X Addressing 01 08 space addressing violation Argument/parameter 01 OC parameter reference violation Computation 02 decimal data 06 floating-point overflow X 07 floating-point underflow X 09 floating-point invalid operand 10 Other 1 Exception 0A size X 0C invalid floating-point conversion X 0D floating-point inexact result X Damage encountered X 04 system object damage state Chapter 2. Computation and Branching Instructions 2-179 Multiply (MULT) Operands XXX Exception 1 44 1C partial system object damage 2 Other 3 [4, 5] X Machine-dependent exception 03 machine storage limit exceeded 20 22 X Machine support 02 machine check X 03 function check X Object access XXX XXX XXX XXX XXX 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution 04 invalid branch target 2E Resource control limit 01 user profile storage limit 36 X exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-180 Negate (NEG) Negate (NEG) Op Code NEG Operand [3-6] Receiver Operand Source Indicator options Receiver Source Indicator targets Branch options Receiver Source Branch targets Operand Extender (Hex) 1 2 1056 NEGI 1856 NEGB 1C56 Operand 1: Numeric variable Operand 2: Numeric Operand 3-6: scalar. Branch Form - Branch number. » number, or absolute instruction point, instruction pointer, relative instruction Form - Numeric variable scalar or character variable indicator . scalar. scalar. Short forms Op Code NIGS Operand Extender (Hex) Operand 1 [2-5] Receiver/Source 1156 NSGIS Indicator options Receiver/Source Indicator targets Branch options Receiver/Source Branch targets 1956 NEGBS 1 D56 Numeric variable Operand 1: Operand 2-5: Branch Form - Branch number. . • Indicator scalar. number, or absolute instruction point, instruction pointer, relative instruction Form - Numeric variable scalar or character variable scalar. The numeric value in the source operand is changed as negative one (-1). The result is placed in the receiver operand. if it Description: The sign changing formed as follows: • operand value and negative to (positive to negative positive) is per- Binary « of the source had been multiplied by a Extract the numeric value and form the twos complement of it. Packed/Zoned - Extract the numeric value and force its sign to positive if it is negative or to negative if it is positive. ® Floating-point Chapter 2. Computation and Branching Instructions 2-181 Negate (NEG) ^^^ 0 têTitTsôsitive' The Significand sign to positive if jt is negative or to nega- result of the operation is copied into the receiver operand. If this operand is not the same type as performing the operation, the resultant value is converted to its type. If necessary the resu ant value is adjusted to the length of the receiver operand, aligned at the assumed decimal point of the rece'ver operand, or both before being copied to it. If significant digits are truncated on the left end of the resultant value, a s/ze (hex OCOA) exception is signaled. An attempt to negate a ma*m m 10 3 Si9ned bina SCa ar ° f S3me S 2e 3150 OCOA) exception. When the receiver is binary , the size exception may be suppressed by using the suppress binary size exception attribute on the Create Program (CRTPG) instruction If a packed^r zonedd P 0 is negated, the result is always positive 0. that used in “I™ When ^ ^ ' ~ -"s '' the source floating-point operand represents not-a-number, the sign is not altered in the receiver. forced to positive and this value For a fixed-point operation, i "" (hex ° C0A if significant digits are truncated from the is s ‘ 9 naled. binary scalar of the same An attempt size also results in to negate a a size (hex left maximum field of the source negative is signaled maTvaleZo a OCOA) exception. th3t inVO Ve 3 flxed -P° int ^ceiver field, if nonzero digits reSUltant Va Ue 3 " /nva/W Rating-point conversion ' not end of the resultant value a ' 6 is would be trun- (hex 0C0C) exception ’ For a floating-point receiver operand, if the exponent of the resultant value is either too large or too epr sented In receiver held, the floating-point overflow (hex 0C06) and 'T the floatingn w f ® point underflow (hex 0C07) exceptions are signaled. a decimal to binary conversion causes a size (hex OCOA) exception to be signaled or if the size was suppressed, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. If exception Resultant Conditions • Positive-The algebraic value of the receiver operand • Negative-The algebraic value of the receiver operand • Zero-The algebraic value of the receiver operand is is is positive. negative. zero. Unordered-The value assigned a floating-point receiver operand is NaN. Exceptions Operands Exception 06 1 2 X X Other Addressing 01 space addressing violation 02 boundary alignment X X X X X X X X 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0C parameter reference violation Computation 02 decimal data X Chapter 2. Computation and Branching Instructions 2-182 Negate (NEG) Operands 1 Exception 06 floating-point overflow 09 floating-point invalid operand size 0C invalid floating-point conversion X 0D floating-point inexact result X 04 system object 1C X XXX XXX Damage encountered partial X X 0A 44 Other X 07 floating-point underflow 10 2 X damage system object damage Machine-dependent exception X 03 machine storage limit exceeded 20 Machine support X 02 machine check X 03 function check 22 Object access 01 object not found 02 object destroyed 03 object suspended X X X X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Resource control X X X limit 01 user profile storage limit 36 X Program execution 04 invalid branch target 2E X X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-183 Not (NOT) Not (NOT) Op Code (Hex) Extender Operand NOT Operand 2 1 Receiver Source 108A Operand [3-4] NOTI 188A Indicator options Receiver Source Indicator targets NOTB Branch options Receiver Source Branch targets 1C8A Operand 1: Operand 2: Operand 3-4: Character variable scalar or numeric variable scalar. Character variable scalar or numeric variable Branch Form- Branch 1 1 • m 1 1 IUCI point, instruction pointer, relative instruction number, or absolute instruction . Indicator Form- Numeric variable scalar or character variable scalar. Short forms Op Code NOTS 1 (Hex) Extender Operand [2-3] 18A NOTIS Indicator options Receiver/Source Indicator targets Branch options Receiver/Source Branch targets 198 A NOTBS 1 Operand 1 Receiver/Source D8A Operand Operand • • Character variable scalar or numeric variable scalar. 1: 2-3: Branch Form- Branch point, instruction pointer, relative instruction number, or absolute instruction Indicator Form- Numeric variable scalar or character variable scalar. The Boolean NOT operation Description: resulting string is placed in is performed on the string value in the source operand, The operands may be character or numeric scalars. They are both interpreted as stringing is supported for both character and numeric operands. The length of the operation The bit Source l he the receiver operand. is bit strings. Sub- equal to the length of the source operand. values of the result are determined as follows: Bit Result Bit 0 1 1 0 Chapter 2. Computation and Branching Instructions 2-1 84 Not (NOT) The result value place on the is right. then placed (left-adjusted) in the receiver operand with truncating or padding taking The pad value used in this instruction is a hex 00 byte. length value of zero) may be Substring operand references that allow for a null substring reference (a reference for the source specified for operands 1 and 2. The effect of specifying a null substring a null operand is that the result is all zero and the instruction's resultant condition is zero. When instruction's resultant condisubstring reference is specified for the receiver, a result is not set and the tion is zero regardless of the value of the source operand. possible that the result produced will not due to truncation, or be a valid value for the numeric type. This can occur due to padding with hex 00, and due to the resultant bit string produced by the instruction. The instruction completes normally signals no exceptions for these conditions. When the receiver operand is a numeric variable scalar, it is Resultant Conditions . • Zero-The bit reference is value for the bits of the scalar receiver operand is either all zero or a null substring specified for the receiver. Not zero-The bit value for the bits of the scalar receiver operand is not all zero. Exceptions Operands 06 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X X X X X X X Addressing 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object damage state 44 1C partial system object damage Machine-dependent exception 03 machine storage 20 limit X exceeded Machine support X 02 machine check X 03 function check 22 Object access X X 02 object destroyed X X 03 object suspended X X 01 object not found X 08 object compressed 24 Other 1 Exception Pointer specification 01 pointer does not exist 02 pointer type invalid Chapter 2. X X X X Computation and Branching Instructions 2-185 Not (NOT) Operands Exception 1 2C 2 04 invalid branch target 2E Resource control X limit 01 user profile storage limit 36 Other Program execution exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-186 Or (OR) Or (OR) Op Code OR Operand Operand 3 Receiver Operand 2 Source 1 Receiver Source 1 Source 2 Indicator targets Receiver Source 1 Source 2 Branch targets Operand Extender (Hex) 1 [4-5] Source 2 1097 ORI Indicator 1897 options ORB Branch options 1C97 Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3: Character scalar or numeric scalar. Operand 4-5: Branch Form - Branch number. . Form-Numeric variable scalar or character variable Indicator • point, instruction pointer, relative instruction number, or absolute instruction scalar. Short forms Op Code ORS 1 Operand 2 Source 2 Operand Receiver/Source Indicator options Receiver/Source 1 Source 2 Indicator targets Branch options Receiver/Source 1 Source 2 Branch targets Operand Extender (Hex) 1 [3-4] 1197 ORIS 1997 ORBS 1 D97 Operand 1: Character variable scalar or numeric variable scalar. Operand 2: Character scalar or numeric scalar. Operand 3-4: • • Branch Form - Branch number. Indicator Description: The point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable The Boolean resulting string is OR placed performed on the the receiver operand. operation in is number, or absolute instruction scalar. string values in the source operands. The operands may be character or numeric scalars. They are both interpreted as stringing is supported for both character and numeric operands. bit strings. Sub- The The length of the operation is equal to the length of the longer of the two source operands. bytes in the excess The hex 00. with right the padded on logically is operands shorter of the two longer operand are assigned to the results. Chapter 2. Computation and Branching Instructions 2-187 Or (OR) The values of the result are determined as follows: bit Source 1 Bit Source 2 0 Bit Result Bit 0 h ® reSU L place o ValUe S h n Placed on 'l the .i right. lThe ! (left ' adjusted) in pad value used in this the rece iver operand with truncating or padding taking is a hex 00. instruction Substring operand references that allow for a null substring reference (a length value of zero) may be ai 1, 2 and 3 The eff6Ct of specifying a null substring reference for one source "‘IS. on^lnH operand is^h°t?h that the other source operand is ORed with an equal length string of all hex 00s This causes the value of the other operand to be assigned to the result. When a null substring reference is both source operands, the result is all zero and the instruction's resultant condition is Trn Wh zero. When a null substring reference is specified for the receiver, a result is not set and the instruction's resultant condition is zero regardless of the values of the source operands. ' ’ •' If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, Vanable ,engths and arra y s with variable subscripts), the results are not a hvayTpred jcta buT ’ hen the receiver operand is a numeric variable scalar, it is possible that the result produced will not be a valid value for the numeric type. This can occur due to padding with hex 00, due to truncation or due to the resultant bit string produced by the instruction. The instruction completes normally and signals no exceptions for these conditions. ’ Resultant Conditions Zero-The bit reference is value for the bits of the scalar receiver operand specified for the receiver. Not zero-The bit value for the bits of is either the scalar receiver operand is all not zero or a all null substring zero. Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 parameter reference violation X X X Other X X X X X X X X X X X X X X X X X X X X Damage encountered 04 system object 44 1C 3 Argument/parameter 01 10 i Addressing partial damage state system object damage Machine-dependent exception Chapter 2. Computation and Branching Instructions 2-188 Or (OR) Operands 1 Exception 03 machine storage 20 22 limit 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 03 object suspended 08 object compressed Pointer specification 01 pointer does not exist 02 pointer type invalid Resource control X limit 01 user profile storage limit 36 X Program execution 04 invalid branch target 2E Other Machine support 02 object destroyed 2C 3 X 01 object not found 24 2 exceeded X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-1 89 Remainder (REM) Remainder (REM) Op Code REM (Hex) Extender Operand 1 Remainder Operand Dividend Divisor Remainder Dividend Divisor Indicator targets Remainder Dividend Divisor Branch targets Operand 2 Operand 3 [4-6] 1073 REMI Indicator 1873 options REMB Branch options 1C73 Operand 1: Operand 2. Numeric scalar. Operand 3: Numeric scalar. Operand 4-6: Numeric variable * Branch Form - Branch number. • Indicator scalar. point, instruction pointer, relative instruction Form - Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code (Hex) Extender Operand REMS Operand 2 1 Operand [3-5] Remainder/Dividend Divisor Indicator options Remainder/Dividend Divisor Indicator targets Branch options Remainder/Dividend Divisor Branch targets 1173 REMIS 1973 REMBS 1 D73 Operand 1: Operand 2: Operand 3-5: Numeric variable Numeric scalar. Branch Form - Branch number. • Indicator Description: remainder in scalar. point, instruction pointer, relative instruction Form - Numeric number, or absolute instruction variable scalar or character variable scalar. The Remainder operand 1. is the result of dividing the Dividend by the Divisor and placing the Operands can have packed or zoned decimal, signed or unsigned binary Source operands are the Dividend and Divisor. The receiver operand If is type. the Remainder. operands are not of the same type, source operands are converted according to the following Chapter 2. Computation and Branching Instructions rules: 2-190 Remainder (REM) 1. 2. any one of the operands has zoned or packed decimal type, source operands are converted to packed decimal. If Otherwise, the binary operands are converted to a logically treated as signed binary(4) scalars. like type. Note: unsigned binary(2) scalars are Source operands are divided according to their type. Packed decimal operands are divided using packed decimal division. Unsigned binary division is used with unsigned source operands. Signed binary operands are divided using two's complement binary division. if all operands have the same packed decimal division. Better performance can be obtained division execute faster than Floating-point is type. Signed and unsigned binary not supported for this instruction. the divisor has a numeric value ofO, a zero divide (hex OCOB) exception has a value of 0, the result of the division is a zero value remainder. If is signaled. If the dividend For a decimal operation, the internal quotient value produced by the divide operation is always calculated with a precision of zero fractional digit positions. If necessary, internal alignment of the assumed decimal point for the dividend and divisor operands is performed to insure the correct precision for the resultant quotient value. These internal alignments are not subject to detection of the decimal point alignment exception. An internal quotient and the corresponding remainder value will be calculated for any combination of decimal attributes which may be specified for the instruction's operands. However, as described below, the assignment of the remainder value is limited to that portion of the remainder value which fits in the remainder operand. If the dividend is shorter than the divisor, it is logically adjusted to the length of the divisor. performed according to the rules of algebra. Unsigned binary is treated as a positive number for the algebra. Before the remainder is calculated, an intermediate quotient is calculated. The attributes of this quotient are derived from the attributes of the dividend and divisor oper- The division operation ands as is follows: Intermediate Dividend IM.SIM or SBIN(2) Divisor Quotient IM.SIM or SBIN(2) SBIN(2) IM.SIM or SBIN(2) SBIN(4) SBIN(4) IM,SIM,SBIN(2) or UBIN(2) DECIMAL(P2,Q2) DECIMAL( 5+02,0) IM,SIM,SBIN(2) or SBIN(4) UBIN(2) or UBIN(4) UBIN(4) UBIN(2) or UBIN(4) IM.SIM, SBIN(2) or SBIN(4) UBIN(4) UBIN(2) or UBIN(4) UBIN(2) or UBIN(4) UBIN(4) SBIN(4) IM.SIM or SBIN(2) SBI N(4) SBIN(4) or UBIN(4) DECIMAL(P2,Q2) DECIMAL(1 0+02,0) DECIMAL(P1 ,01 !M,SIM,SBIN(2) or UBIN(2) DECIMAL(PI.O) DECIMAL(P1 ,01 SBIN(4) or UBIN(4) DECIMAL(PI.O) DECIMAL(P1 ,01 DECIMAL(P2,02) DECIMAL(P1-O1+O,0) Where O = Larger IM of 01 or 02 = IMMEDIATE SIM = SIGNED IMMEDIATE SBIN = SIGNED BINARY Chapter 2. Computation and Branching Instructions 2-191 Remainder (REM) = UNSIGNED BINARY DECIMAL = PACKED OR ZONED UBIN After the intermediate quotient remainder operand Remainder = is numeric value has been determined, the numeric value of the calculated as follows: Dividend - (Quotient*Divisor) When signed arithmetic is used, the sign of the remainder is the same as that of the dividend unless the remainder has a value of 0. When the remainder has a value ofO, the sign of the remainder is positive. The resultant value of the calculation is copied into the remainder operand. If this operand is not the type as that used in performing the operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the length of the remainder operand, aligned at the assumed decimal point of the remainder operand, or both before being copied to it. same If significant digits are truncated on the left end of the resultant value, a size (hex 0C0A) exception signaled for those programs that request to be notified of size exceptions. is If a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled in programs that request to be notified of size exceptions, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. Resultant Conditions • • • Positive-The algebraic value of the numeric scaler remainder is Negative-The algebraic value of the numeric scaler remainder Zero-The algebraic value of the numeric scaler remainder is is positive. negative. zero. Exceptions Operands Exception 06 01 08 space addressing violation 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X Computation 02 decimal data 0A size X 0B zero divide 10 X Damage encountered 04 system object 44 1C Other Argument/parameter 01 parameter reference violation OC 1 Addressing partial damage state system object damage X X X X X X X X Machine-dependent exception Chapter 2 . Computation and Branching Instructions 2-192 Remainder (REM) Operands Exception 03 machine storage 20 22 1 limit 2 3 Machine support 02 machine check X 03 function check X Object access found X X X 02 object destroyed X X X 03 object suspended X X X 01 object not X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X X X Program execution X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 36 Other X exceeded X exceeded Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-1 93 Scale (SCALE) Scale (SCALE) Op Code SCALE (Hex) Extender Operand Operand 1 Operand 3 2 Operand [4-7] Receiver Source Scale factor Receiver Source Scale factor Indicator targets Receiver Source Scale factor Branch targets 1063 SCALEI Indicator 1863 options SCALES Branch options 1C63 Operand 1: Operand 2: Numeric Operand 3: Binary(2) scalar. Operand 4-7: Numeric variable scalar. scalar. ° Branch Form- Branch number. 0 Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code SCALES (Hex) Extender Operand Operand 2 1 Operand [3-6] Receiver/Source Scale factor Indicator options Receiver/Source Scale factor Indicator targets Branch options Receiver/Source Scale factor Branch targets 1163 SCALEIS 1963 SCALEBS 1 D63 Operand 1: Operand 2: Operand 3-6: Numeric variable scalar. Binary(2) scalar. * Branch Form- Branch number. ° Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. The scale instruction performs numeric scaling of the source operand based on the scale and places the results in the receiver operand. The numeric operation is as follows: Description: factor Operand 1 = Operand 2 *(B**N) where: N is the binary integer value of the scale operand. It can be positive, negative, or the operation simply copies the source operand value into the receiver operand, B is the arithmetic base for the type of numeric value in Chapter 0. If N is 0, then the source operand. 2. Computation and Branching Instructions 2-1 94 Scale (SCALE) Base Type B Binary 2 Packed/Zoned 10 Floating-point 2 The scale operation is a shift of N binary, packed, or zoned digits. The shift is to the left if N is posithe right if N is negative. For a floating-point source operand, the scale operation is performed as if the source operand is multiplied by a floating-point value of 2**N. tive, to If the source and receiver operands have different attributes, the scaling operation is done in an intermediate field with the same attributes as the source operand. If a fixed-point scaling operation causes nonzero digits to be truncated on the left end of the intermediate field, a size (hex 0C0A) exception is signaled. For a floating-point scaling operation, the floating-point overflow (hex 0C06) and the floatingpoint underflow (hex 0C07) exceptions can be signaled during the calculation of the intermediate result. The resultant value of the calculation is copied into the receiver operand. If this operand is not the same type as that used in performing the operation, the resultant value is converted to its type. If necessary, the resultant value assumed decimal ations, if nonzero is adjusted to the length of the receiver operand, aligned point of the receiver operand, or both before being copied to digits are truncated off the left it. at the For fixed-point oper- end of the resultant value, a size (hex 0C0A) exception signaled. is fields, if nonzero digits would be truncated end of the resultant value, an invalid floating-point conversion (hex 0C0C) exception is For floating-point operations involving fixed-point receiver from the left signaled. fields, if the exponent of the resultant value is either too large or too small to be represented in the receiver field, the floating-point overflow (hex 0C06) or floating-point underflow (hex 0C07) exception is signaled. For floating-point receiver A scalar value invalid (hex 3203) exception particular type of the source Maximum -15 < N < 15 Unsigned Binary(2) -16 < N < 16 Signed Binary(4) -31 < N < 31 Unsigned Binary(4) -32 < N < 32 Decimal(P,0) -31 < N < 31 in signaled floating-point, in if the value of N is beyond the range of the the following table. Value of N Source Operand Type Signed Binary(2) For a scale operation is operand as specified no limitations are placed on the values allowed for N other than the implicit limits imposed due to the floating-point overflow and underflow exceptions. Limitations: If The following are limits that apply to the functions performed by this instruction. a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits. Resultant Condition • Positive-The algebraic value of the receiver operand • Negative-The algebraic value of the receiver operand • Zero-The algebraic value of the receiver operand is is positive. is negative. zero. Chapter 2. Computation and Branching Instructions 2=195 Scale (SCALE) • Unordered-The value assigned a floating-point receiver operand is NaN. Exceptions Operands Exception 06 1 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X Addressing 01 08 space addressing violation Argument/parameter 01 0C parameter reference violation Computation 02 decimal data X 06 floating-point overflow X 07 floating-point underflow X 09 floating-point invalid operand 10 X 0A size X 0C invalid floating-point conversion X 0D floating-point inexact result X X Damage encountered 04 system object 44 1C partial damage state system object damage X X X X X X X X Machine-dependent exception 03 machine storage limit exceeded 20 22 X Machine support 02 machine check X 03 function check X Object access 01 object not found X X X 02 object destroyed X X X 03 object suspended X X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X X X Program execution 04 invalid branch target 2E Other Resource control X limit 01 user profile storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-196 Scale (SCALE) 12 Operands Exception Scalar specification 32 Other X 03 scalar value invalid 36 3 Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-197 Scan (SCAN) Scan (SCAN) Op Code (Hex) Operand Extender SCAN Operand Base 1 Receiver Operand 3 2 Operand [4-5] Compare 10D3 operand SCANS Branch options Receiver Compare Base 1CD3 Branch targets operand SCANI Indicator 18D3 options 1: Binary variable scalar or binary array. Operand 2: Character variable scalar. Operand 3: Character scalar. Operand 4-5: Branch Form - Branch number. • Indicator Description: Indicator targets operand Operand • Compare Base Receiver point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable The character string value of the base operand compare operand. is number, or absolute instruction scalar. scanned for occurrences of the character string value of the The base and compare operands must both be character must not be greater than that of the base string. strings. The length of the compare operand The operation begins at the left end of the base string and continues character by character, from left comparing the characters of the base string with those of the compare operand. The length of the comparisons are equal to the length of the compare operand value and function as if they were being compared in the Compare Bytes Left-Adjusted instruction. to right, If a set of bytes that match the its If compare operand leftmost base string character the receiver operand array, as is is placed a scalar, only the many occurrences in is found, the binary value for the ordinal position of the receiver operand. first occurrence of the compare operand as there are elements in is noted. The operation continues until no more occurrences of the compare operand can be noted in the receiver operand or until the number of characters (bytes) remaining to be scanned in the base is less than the length of the compare operand. When the second condition occurs, the receiver value all its remaining elements are also set to is If it an the array are noted. is set to 0. If the receiver operand is string an array, 0. The base operand and the compare operand can be variable length substring compound operands. Substring operand references that allow for a null substring reference (a length value of zero) may be specified for operands 2 and 3. The effect of specifying a null substring reference for the compare operand or both operands is that the receiver is set to zero (no match found) and the instruction's compare operand. Specifying a null substring reference for just the base due to the requirement that the length of the compare operand must not be of the base string. resultant condition operand is is null not allowed greater than that Chapter 2. Computation and Branching Instructions 2-1 98 Scan (SCAN) Resultant Conditions • Zero-The numeric value(s) of the receiver operand is zero. When the receiver operand is an array, the resultant condition is zero if all elements are zero. One of these two conditions will result when the compare operand is not a null substring reference. • Positive-The numeric value(s) of the receiver operand » Null is positive. compare operand-The compare operand is a null substring reference; therefore, the receiver been set to zero which indicates that no occurrences were found. has Exceptions Operands Exception 06 1 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0C parameter reference violation X X X X X X X X X X Damage encountered 04 system object 44 1C Other Computation 08 length conformance 10 3 XXX XXX XXX XXX XXX Addressing 01 2 partial damage state system object damage Machine-dependent exception 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management Chapter 2. Computation and Branching Instructions 2-199 Scan (SCAN) Operands Exception 01 1 space extension/truncation 2 3 Other X Chapter 2. Computation and Branching Instructions 2-200 Scan with Control (SCANWC) Scan with Control (SCANWC) Op Code Operand Extender 1 Operand 2 Operand 3 Operand 4 Operand [5-8] (Hex) SCANWC Base 10E4 locator Controls Escape Options target or null SCANWC B Branch Base 1CE4 options locator Controls Options Escape Branch target or targets null SCANWCI Indicator Base 18E4 options locator Options Controls Escape Indicator target or targets null Operand 1: Space Operand 2: Character(8) variable scalar (fixed length) Operand 3: Character(4) constant scalar (fixed length) Operand 4: Instruction tion definition Operand list pointer. number, element, or relative instruction number, branch point, instruction pointer, instruc- null. 5-8: ‘ Branch Form - Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Description: The base string to be scanned is specified by the base locator and controls operands. The base locator addresses first character of the base string. The controls specifies the length of the base string in the base length field. The scan operation begins at the left end of the base string and continues character by character, leftto-right. The scan operation can be performed on a base string which contains all simple (1-byte) or all extended (2-byte) character codes or a mixture of the two. When the base string is being interpreted in simple character mode, the operation moves through the base string one byte at a time. When the base string is being interpreted in extended character mode, the operation moves through the base string 2 bytes at a time. The character string value of the base operand is scanned for occurrences of a character value satisfying the criteria specified in the control and options operands. The scan completed by updating the base locator and controls operands with scan status when a is found, the end of the base string is encountered, or an escape code is encountered when the escape target operand is specified. The base locator is set with addressability to the character (simple or extended) which caused the instruction to complete execution. The controls operand is set with information which identifies the mode (simple or extended) of the base string character addressed by the base locator and which provides for resumption of the scan operation with minimal overhead. is character value being scanned for The controls and options operands specify the modes to be used in interpreting characters during the scan operation. Characters can be interpreted in one of two character modes: simple (1-byte) and extended (2-byte). Additionally, the base string can be scanned in one of two scan modes, mixed (base string may contain a mixture of both character modes) and nonmixed (base string contains one mode of characters). Chapter 2. Computation and Branching Instructions 2-201 Scan with Control (SCANWC) When the mixed scan mode is specified in the options operand, the base string is interpreted as conand extended character codes. The mode, simple or extended, with which the string is to be interpreted, is controlled initially by the base mode indicator in the controls operand and thereafter by mode control characters imbedded in the base string. The mode control characters taining a mixture of simple are as follows: • Hex OE = • Hex OF occurs When = in Shift out first mode to extended mode. mode from extended mode. This only recognized is if it byte position of an extended character code. mode the nonmixed scan shifting simple character Shift in (SI) to the mode only the character mode (SO) of simple character is specified in specified by the base can not occur because no mode the options operand, the base string mode indicator in is interpreted using the controls operand. Character when scanning control characters are recognized in nonmixed mode. The base input, locator operand locates the it first space pointer which a is is both input to and output from the instruction. character of the base string to be processed. On output, it On locates the character of the base string which caused the instruction to complete. The controls operand must be control the scan operation. It a character scalar which specifies additional information to be used to must be at least 8 bytes long and have the following format: Controls operand Char(8) — Control indicators Char(1) — Reserved Char(1) — Comparison — Reserved — Base characters Char(2) Char(1) end Char(3) work area - Instruction - Base length Char(1) Char(2) Only the first 8 bytes of the controls operand are used. Any excess bytes are ignored. Reserved must contain binary zeros. The control indicators field has the following format: • Control indicators fields Char(1) — Base mode 0 = Simple = Extended — Comparison character mode 0 = Simple = Extended Bit 0 1 Bit 1 1 — Reserved (must be — Scan state 0 1 Bit 2-6 0) Bit 7 = Resume scan = Start scan The base mode the character in is both input to and output from the instruction. In either case, it specifies the mode of the base string currently addressed by the base locator. The comparison character mode parison character contained in is not changed by the instruction. It specifies the mode of the com- the controls operand. Chapter 2. Computation and Branching Instructions 2-202 Scan with Control (SCANWC) The scan state is both input to and output from the instruction. As input, operation for the base string is that the base length value the base in being started or resumed. end If it is it indicates whether the scan being started the instruction assumes , the controls operand specifies the length of the base ignored. If it is being resumed, the instruction assumes field of and the instruction work area value is the base end field has been set by a prior start scan execution of the instruction with an machine value identifying the end of the base string. string, internal For a start scan execution of the instruction, the scan state field is reset to indicate resume scan to provide for subsequent resumption of the scan operation. Additionally, for a start scan execution of the instruction, the base end field is set with an internally optimized value which identifies the end of the base string being scanned. This value then overlays the values which were in the instruction work area and base length fields on input to the instruction. Predictable operation of the instruction on a this base end field being left intact with the value set by the start resume scan execution depends upon scan execution. For a resume scan execution of the instruction, the scan state and base end fields are unchanged. The comparison character is input to the instruction. It specifies a character code to be used in the comparisons performed during the scanning of the base string. The comparison character mode in the control indicators specifies the mode (simple or extended) of the comparison character. If it is a simple character, the first byte of the comparison character field is ignored and the comparison character is assumed to be specified in the second byte. If it is an extended character, the comparison character is specified as a 2-byte value in the comparison character field. The base end field is both input to and output from the instruction. It contains data which identifies the end of the base string. Initially, for a start scan execution of the instruction, it contains the length of the base string in the base length field. Additionally, the base end field is used to retain information over multiple instruction executions which provides for minimizing the overhead required to resume the scan operation for a particular base string. This information is set on the initial start scan execution of the instruction and is used during subsequent resume scan executions of the instruction to determine the end of the base string to be scanned. If the end of the base string being scanned must be altered during iterative usage of this instruction, a start scan execution of the instruction must be performed to provide for correctly resetting the internally optimized value to be stored in the base end from the values specified in the base locator operand and base length field. For the special case of a start scan execution where a length value of zero (no characters to scan) is in the base length field, the instruction results in a not found resultant condition. In this case, the base locator is not verified and the scan state indicator, the base end field, and the base locator specified are not changed. The options operand must be a character scalar which specifies the options to be used scan operation. It must be at least 4 bytes in length and has the following format: • Options operand Char(4) — Options indicators Char(1) — Reserved Char(3) The options operand must be specified as to control the a constant character scalar. Only the first 4 bytes of the options operand are used. Any excess bytes are ignored. Reserved must contain binary zeros. The option indicators field has the following format: Option indicators Char(1) — Reserved Bit 0 — Scan mode Bit Chapter 2. fields 1 Computation and Branching Instructions 2-203 Scan with Control (SCANWC) = Mixed = Nonmixed 0 1 Reserved Bits 2-3 Comparison - Equal, = ( Bits 4-6 relation ) relation Bit 4 - Less than, (<) relation Bit 5 - Greater than, (>) relation Bit 6 0 1 = No match = Match on on relation relation Reserved Bit 7 The scan mode specifies whether the base string contains a mixture of character modes, or contains all one mode of characters; that is, whether or not mode control characters should be recognized in the base string. Mixed specifies that there is a mixture of character modes and, therefore, mode control characters should be recognized. Nonmixed specifies that there is not a mixture of character modes and, therefore, indicator in mode control characters should not be recognized. the controls operand specifies the character mode of the base Note that the base mode addressed string character by the base locator. The comparison relation specifies the relation or relations of the the base string which will satisfy of the high, low, or equal resultant conditions. one another. Specifying comparison character to characters of the scan operation and cause completion of the instruction with one Multiple relations may be specified in conjunction with match against any character in the base string which is of the same mode as the comparison character. Specifying no relation insures a not found resultant condition, in the absence of an escape due to verification, regardless of the values of the characters in the base string which match the mode of the comparison character. all relations insures a An example of comparison scanning is a scan of simple mode characters for a value less than hex 40. This could be done by specifying a comparison character of hex 40 and a comparison relation of greater than in conjunction with a branch option for the resultant condition of high. This could also be done by specifying a comparison character of hex 3F and comparison relations of equal and greater than in conjunction with branch options for equal and high. The target of the branch options in either case would be the instructions to process the character less than hex 40 in value. The escape target operand controls the 40. Verification, if requested, verification of bytes of the base string for values less than hex always performed in conjunction with whatever comparison processing verification is performed even if no comparison relation is specified. This is has been requested. That is, operand is discussed in more detail in the following material. During the scan operation, the characters of the base string which are not of the same mode as the comparison character are skipped over until the mode of the characters being processed is the same as the mode of the comparison character. The operation then proceeds by comparing the comparison character with each of the characters of the base string. These comparisons behave as if the characters If were being compared in the Compare Bytes Left Adjusted instruction. a base string character satisfying the criteria specified the base locator mode is set to address the byte of it, in the controls and options operands the base mode of the base string as of that character, and the instruction resultant condition based on the to the first base comparison relation is indicator is is found, set to indicate the completed with the appropriate comparison character {high, low, or equal) of the string character. Chapter 2. Computation and Branching Instructions 2-204 Scan with Control (SCANWC) If base a matching string character is not found prior to encountering a mode change, the characters of the base string are again skipped over until the mode of the characters being processed as the mode of the comparison character before comparisons are resumed. If a matching base string character base location is set to address the is is the same not found prior to encountering the end of the base string, the first byte of the character encountered at the end of the base string, mode of the base string as of that character, and the completed with the not found resultant condition. A mode control string results in the changing of the base string mode, but the base locator is left addressing the mode control character. the base mode instruction indicator set to indicate the is is If the escape target operand is specified (operand 4 is not null), verifications are performed on the characters of the base string prior to their being skipped or compared with the comparison character. Each byte of the base string is checked for a value less than hex 40. Additionally, for a mixed scan mode, when such a value • • when Hex 0E (SO) Hex OF (SI) in the is encountered, the base string left is it is then determined being interpreted byte of the character code when in if it is a valid mode control character. simple character mode. the base string is being interpreted is considered to be an in extended character mode. If a byte value of less than hex 40 base locator is mode not a valid set to address the control character, it byte of the base string character (simple or escape code. The extended) which contains the escape code, the base mode indicator is set to indicate the mode of the base string as of that character, and a branch is taken to the target specified by the escape target operand. When the escape target branch is performed, the value of any optional indicator operands is is first meaningless. codes in the base string are not performed. However, for a mixed scan mode, mode control values are always processed as described previously under the discussion of the mixed scan mode. If the escape target operand If possible, use a overhead If is is not specified (operand 4 is null), verifications of the character Space Pointer Machine Object for the base locator, operand 1. Appreciably incurred in accessing and storing the value of the base locator if this is done. possible, specify through its ODT is operand on an 8-byte multiple (doubleword) Appreciably less overhead is incurred in done. definition, the controls boundary relative to the start of the space containing accessing and storing the value of the controls if this For the case where a base string less to be just it. is scanned for byte values less than hex 40, two techniques can be used. • A direct simple mode scan for a value less than hex 40 without usage of the escape target verification feature. » A scan The for direct any character with usage of the escape target scan approach, the former, is the more verification feature. efficient. The following diagram defines the various conditions which can be encountered at the end of the base string and what the base locator addressability is in each case. The solid vertical line represents the end of the base string. The dashes represent the bytes before and after the base string end. The V is positioned over the byte addressed by the base locator in each case. These are the conditions which can be encountered when the base locator input to the instruction addresses a byte prior to the base string end. When the base length field specifies a value of zero for a start scan execution of the instruction, or the input base locator addresses a point beyond the end of the instruction, no processing is performed and the instruction is immediately completed with the not found resultant condition. Chapter 2. Computation and Branching Instructions 2-205 Scan with Control (SCANWC) Addressability V Ending Condition Instruction Response (OnB byte code at string end) I • Simple character 9 Shift in/cut encountered • Appropriate resultant condition indicating found or not found Mode shift performed, and not found resultant condition Escape code simple in • Branch taken • Not found resultant character (Extended character across string end) • split Extended character condition Escape code In extended • Branch taken character V (Extended character at string end) B Extended character Appropriate resultant condition indicating found or not found 0 Escape code Branch taken in extended character AACOTg-0 An shows that normally, after appropriate processing for the particular found, not found, or escape condition, the scan can be restarted at the byte of data which would follow the base string end in the data stream being scanned. Any mode shift required by an ending mode control character will have been performed. analysis of the diagram However, one ending condition may require subsequent resumption of the scan at the character encountered at the end of the base string. This is the case where the instruction completes with the not found resultant condition and the base string ends with an extended character split across string end. That is, the base mode indicator specifies extended mode, the base locator addresses the last byte of the base string, and that byte value is not a shift out, hex OE character. In this case, complete verification of the extended character and relation comparison could not be performed. If this extended character is to be processed, it must be done through another execution of the Scan instruction where both bytes of the character can be input to the instruction within the confines of the base string. Resultant Conditions • Equal: A character value was found controls and options operands in in the base string which satisfies the criteria specified in the comparison character is of equal string value to the base that the string character. High: A character value was found controls and options operands base in in the base string which satisfies the criteria specified in the comparison character is of higher string value to the that the string character. Chapter 2. Computation and Branching Instructions 2-206 Scan with Control (SCANWC) • A Low: character value the base string which satisfies the criteria specified in the that the comparison character is of lower string value to the base was found controls and options operands in in string character. • Not found: in A character value was not found in the base string which satisfied the criteria specified the controls and options operands. Exceptions Operands 1 2 3 4 X X X X 02 boundary alignment X X X X 03 range X X X X 06 optimized addressability invalid X X X X X X X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 OC parameter reference violation Computation 08 length conformance 10 Damage encountered X 04 System object damage state 44 1C partial X system object damage Machine-dependent exception X 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X Object access 01 object not found X X X X 02 object destroyed X X X X X X X X 03 object suspended X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X X X X X Program execution X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 Other X exceeded Scalar specification X 01 scalar type invalid 03 scalar value invalid Chapter 2. X X X X X Computation and Branching Instructions 2-207 Scan with Control (SCANWC) 12 Operands Exception 36 Space 01 management 3 4 space extension/truncation Other X Chapter 2. Computation and Branching Instructions 2-208 Search (SEARCH) Search (SEARCH) Op Code Operand Extender Operand 1 2 Operand 3 Operand 4 Operand [5-6] (Hex) SEARCH Receiver Array Find Location Receiver Array Find Location 1084 SEARCHB Branch 1C84 options SEARCHI Indicator 1884 options Location Find Array Receiver 1: Binary variable scalar or binary variable array. Operand 2: Character array or numeric array. Operand 3: Character variable scalar or numeric variable scalar. Operand 4: Binary scalar. Operand 5-6: Branch Form- Branch number. • Indicator Description: Indicator targets Operand . Branch targets point, instruction pointer, relative instruction number, or absolute instruction Form-Numeric variable scalar or character variable scalar. The portions of the array operand indicated by the location occurrences of the value indicated in operand are searched for the find operand. The operation begins with the first element of the array operand and continues element by element, comparing those characters of each element {beginning with the character indicated in the location operand) with the characters of the find operand. The location operand contains an integer value representing the relative location of the first character in each element to be used to begin the compare. The integer value of the location operand must range from 1 to L, where operand elements; otherwise, a scalar value invalid (hex 3203) exception cates the leftmost character of each element. The array and L is is the length of the array signaled. A value of indi- 1 operands can be either character or numeric. Any numeric operands are intercompares between these operands are performed at the operand and function as if they were being compared in the Compare Bytes Left- find preted as logical character strings. The length of the find Adjusted instruction. find operand must not be so large that it exceeds the length of the array operand elements when used with the location operand value. The array element length used is the length of the array scalar elements and not the length of the entire array element, which can be larger in non- The length of the contiguous arrays. As each occurrence of the find value is encountered, the integer value of the index for this array the receiver operand. If the receiver operand is a scalar, only the first element containing the find value is noted. If the receiver operand is an array, as many occurrences as there are elements within the receiver array are noted. element is placed in Chapter 2. Computation and Branching Instructions 2-209 Search (SEARCH) If the value of the index for an array element containing an occurrence of the find value in the receiver, a size (hex OCOA) exception is signaled. is too large to be contained The operation continues until no more occurrences of elements containing the find value can be noted in the receiver operand or until the array operand has been completely searched. When the second condition occurs, the receiver value is set to LB-1, where LB is the value of the lower bound index of the array. If LB is the most negative 32-bit integer, then LB-1 is the most positive 32-bit integer; otherwise, LB-1 is 1 less than LB. If the receiver operand is an array, all its remaining elements are also set to LB-1. The find operand can be a variable length substring compound operand. Resultant Conditions through UB, where UB The numeric value(s) of the receiver operand is either LB-1 or in the range LB the value of the upper bound index of the array. When the receiver is LB-1, the resultant condition is zero. When the receiver is in the range LB through UB, the resultant condition is positive. When the receiver is an array, the resultant condition is zero if all elements are LB-1; otherwise, it is positive. The resultant condition is unpredictable when the no binary size exception program template option is used. is Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 08 2 3 4 X X X X X X X X X X X X 06 optimized addressability invalid X X X X X X X X X X X X X X X X X X X X Argument/parameter parameter reference violation Computation 08 length conformance 0A 10 size X Damage encountered 04 system object damage state 44 1C partial system object damage Machine-dependent exception 03 machine storage limit exceeded 20 X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found X X X 02 object destroyed X X X X 03 object suspended X X X X X 08 object compressed 24 Other 03 range 01 OC 1 Addressing X Pointer specification 01 pointer does not exist X Chapter 2. X X X Computation and Branching Instructions 2-21 Search (SEARCH) Operands Exception 02 pointer type invalid 2C 1 2 3 4 X X X X Program execution X 04 invalid branch target 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification X 01 scalar type invalid X X X X 03 scalar value invalid 36 Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-211 Set Bit Set Bit Op Code (Hex) Operand Source 101 E 1 Operand 2: : String (SETBTS) String (SETBTS) in Operand in Operand 1 2 Offset Character variable scalar (fixed length) or numeric variable scalar. Binary scalar. Description: The selected Sets the bit bit of the receiver operand as indicated by the from the receiver operand is set to a value of binary bit offset operand. 1. The receiver operand can be a character or numeric variable. The leftmost bytes of the receiver operand are used in the operation. The receiver operand is interpreted as a bit string with the bits numbered The offset left to right from 0 to the total number of bits in the string minus 1. operand indicates which bit of the receiver operand is to be set, with a offset of zero indiof the leftmost byte of the receiver operand. This value may be specified as a constant or any valid binary scalar variable. cating the leftmost bit If a offset value less than zero or beyond the length of the receiver (hex 3203) exception is signaled. is specified a scalar value invalid Exceptions Operands Exception 06 01 08 Spacing addressing violation X X X X 03 Range X X 06 Optimized addressability invalid X X X X Parameter reference violation Damage encountered 04 System object Partial damage state X system object damage X Machine-dependent exception 03 Machine storage 20 limit exceeded X Machine support 02 Machine check X 03 Function check 22 Other Argument/parameter 44 1C 2 02 Boundary alignment violation 01 10 1 Addressing X Object access 02 Object destroyed X X 03 Object suspended X X 08 object compressed X Chapter 2. Computation and Branching Instructions 2-21 Set Bit in String (SETBTS) Operands Exception 24 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X Other X exceeded Scalar specification 01 X Scalar type invalid X X 03 Scalar value invalid 36 2 limit 01 user profile storage limit 32 1 Pointer specification Space management 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-213 Set Instruction Pointer (SETIP) Set Instruction Pointer (SETIP) Op Code (Hex) Operand 1022 Operand 1 Receiver Operand 1 Operand 2: : 2 Branch target Instruction pointer. number, Instruction relative instruction number, or branch point. Descr/pt/ on ; T h e value of the branch target (operand 2) is used to set the value of the instruction y ° per and 1 The ,nstruction number indicated by the branch target must provide thJ address addr? off an instruction t t the within the program containing the Set Instruction Pointer instruction. Exceptions Operands Exception Addressing 01 space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid 08 parameter reference violation Damage encountered 04 system object 44 1C X Argument/parameter 01 10 Other 2 1 06 partial damage state system object damage X X X X X X Machine-dependent exception 03 machine storage limit exceeded 20 X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found X 02 object destroyed X 03 object suspended X 08 object compressed 24 Pointer specification 01 pointer does not exist X 02 pointer type invalid 2C X Program execution 04 branch target invalid 2E Resource control X limit 01 user profile storage limit exceeded X Chapter 2. Computation and Branching Instructions 2-214 Set Instruction Pointer (SETIP) Operands 1 Exception 36 2 Other Space management 01 X space extension/truncation Chapter 2. Computation and Branching Instructions 2-215 Store and Set Computational Attributes (SSCA) Store and Set Computational Attributes (SSCA) Op C° d e (Hex) Operand 1078 Operand 2 Source 1 Receiver Operand 7: Operand 2: Character(5) scalar (fixed length) or null. Operand 3: Character(5) scalar (fixed length) or null. Character^) variable scalar Operand 3 Controls (fixed length). Description: This instruction stores and optionally sets the attributes for controlling computational operations for the process this instruction is executed in. The receiver is assigned the values that each of the computational attributes had It has the same format and bit assignment as the cution of the instruction. at the start of source. The source specifies new values for the computational attributes for the process. The particular computational attributes that are selected for modification are determined by the controls operand. The source operand has the following format: • Floating-point exception = = 0 1 masks Disabled (exception Enabled (exception is is Char(2) masked) unmasked) — Reserved (binary 0) - Floating-point overflow • Bits 0-9 Floating-point underflow — Floating-point zero divide — Floating-point inexact result - Floating-point invalid operand — Reserved (binary Bit 11 = 1 = Bit 13 14 Bit 0) Bit 15 Char(2) Exception has not occurred Exception has occurred — Reserved (binary 0) — Floating-point overflow Bits 0-9 Bit - Floating-point underflow - Floating-point zero divide - Floating-point inexact result - Floating-point invalid - Reserved • 12 Bit Floating-point exception occurrence flags 0 10 Bit - 10 Bit 11 Bit 12 Bit 13 operand Bit 14 (binary 0) Bit 15 Modes Char(1) — Reserved - Floating-point rounding Bit 0 00= Round toward 01 = Round mode Bits 1-2 positive infinity toward negative infinity Chapter 2. Computation and Branching Instructions 2-216 Store and Set Computational Attributes (SSCA) 10= Round toward zero = Round 11 — to nearest (default) Bits 3-7 Reserved the bit values of the The controls operand is used to select those attributes that are to be set from A value of one for a source. the for that as same the is source operand. The format of the controls bit computational attribute for the process is to be set from in controls indicates that the corresponding controls indicates that the corresponding the value of that bit of the source. A value of zero for a bit in will retain the value it had prior to and computational attribute for the process is not to be changed, field, such as the rounding modes, all of this instruction. For an attribute controlled by a multiple-bit must be ones or all must be zeros. A mixture of ones and zeros in such a field the bits results in in the field a scalar value invalid (hex 3801) exception. just return the current computathe source and controls operands are both null, the instruction will of the process are modified attributes tional attributes. If the source is specified, the computational and the controls operand is specified under control of the controls operand. If the source operand is specified in the source. values attributes to the null, the instruction will change all of the computational type (hex 2A06) operand controls operand is specified, an invalid If the source operand is null and the If exception is signaled on the Create Program instruction. the exception processing With the floating-point exception masks field, it is possible to unmask/mask is unmasked occurs, that and handling for each of the five floating-point exceptions. If an exception If is signaled. exception the and then the corresponding floating point exception occurrence bit is set, exception pointer the floating an exception that is masked occurs, the exception is not signaled, but exception. the of occurrence the indicate set to occurrence flag is still The tion occurrence flag for each exception may be set or cleared by from the source operand under control of the controls operand. floating-point exception this instruc- to implicit conversions, all Unless specified otherwise by a particular instruction, or precluded due precision, and then rounded to fit in a floating-point operations are performed as if correct to infinite the result is inexact To allow control destinations format while potentially signaling an exception that process, four floating-point roundin g of the floating-point rounding operations performed within a bracketed most modes are supported. Assume y is the infinitely precise number that is to be rounded, than y and z is the smallest repreclosely by x and z, where x is the largest representable value less following diagram shows this sentable value greater than y. Note that x or z may be infinity. The where the vertical bars denote values progressing numerically of relationship of x, y, and z on a scale values representable in a floating-point format. x Bmaller z y > < Larger AAora-o Given the above, if y change y as follows: is not exactly representable in the receiving field format, the rounding modes even in case of a tie is the default rounding mode in effect upon the to the closer of x or z. If they are equally initiation of a process. For this rounding mode, y is rounded For the purposes of this zero) is chosen. close, the even one (the one whose least significant bit is a case of the y being rounded to a mode of rounding, infinity is treated as if it was even. Except for by at most half of the result value of infinity, the rounded result will differ from the infinitely precise slightly from the decimal differs mode least significant digit position of the chosen value. This rounding mode would rounding This round algorithm performed for the optional round form of an instruction. 1. to that value round a value of 0.5 to 0, where the decimal round algorithm would round Round to nearest with round to Chapter 2. Computation and Branching Instructions 2-217 Store and Set Computational Attributes (SSCA) Round toward rounded to positive infinity indicates directed rounding upward to occur. is ne9at Ve ' ' nfinity indicates directed mundediox Round toward zero magnitude) of x or indicates truncation is rounding downward to occur. For this mode, y is is infinity are exact. Negative infinity is less The floating-point inexact unmasked. • All floating • Round to occur. ’ v 3 is For this mode, y rounded to the smaller than every The computational attributes are set with a default value upon process are as follows. These mode is (in ' z. Arithmetic operations upon less than positive infinity. • For this z. result exception is masked. The other finite value which The default initiation is i attributes floating-point exceptions are point occurrence bits have a zero value. to the nearest rounding mode. attributes can be modified by a program executing this instruction. The new attributes are then the program executing this instruction and for programs invoked subsequent to it unless changed through another execution of this instruction. External exception handlers and invocation exit are nV ° k ed th tde same attributes as were last in effect for the program invocation they are related to. Event h handlers do not really relate to another invocation in the process. As such they are invoked with the attributes that were in effect at the point the process was interrupted to handle the event. in effect for ' Upon ™ return to the invocation of a program from subsequent program invocations, the computational than floating point exception occurrence attributes, are restored to those that were in effec when the program gave up control. The floating point exception occurrence attributes are left intact reflecting the occurrence of any floating-point exceptions during the execution of subsequent ^ ributes, other invocations. internal exception handlers execute under the invocation of the program containing them. As such the computational attributes are restored upon returning from an external excep, tion handler does not^ apply. The execution of an internal exception handler occurs in a manner similar to the execution of an internal subroutine invoked through the Call Internal instruction. If the internal exception handler modifies the attributes, the modification remains in effect for that invocation when the exception handler completes the exception. a T d S CUS slon of ' ow . Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 1 z X X X X X X X X X X X X X X X 3 Other Addressing Argument/parameter 01 parameter reference violation Chapter 2 . Computation and Branching Instructions 2-218 Store and Set Computational Attributes (SSCA) Operands 1 Exception 10 partial Machine-dependent exception limit X exceeded Machine support X 02 machine check X 03 function check 22 Other X system object damage 03 machine storage 20 3 Damage encountered 44 1C 2 Object access X X X 02 object destroyed X X X 03 object suspended X X X 01 object not found X 08 object compressed : 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X X exceeded Scalar specification X 01 scalar type invalid 03 scalar value invalid 36 X limit 01 user profile storage limit 32 X X X X X Space management 01 X space extension/truncation .•I Chapter 2. Computation and Branching Instructions 2-219 Subtract Logical Character (SUBLC) Subtract Logical Character (SUBLC) Op Code SUBLC (Hex) Extender Operand Difference Operand Minuend Difference Minuend Subtrahend Indicator targets Difference Minuend Subtrahend Branch targets 1 2 Operand 1027 SUBLCI Indicator 1827 options SUBLCB Branch options 1C27 Operand 1: Operand 2: Character scalar (fixed-length). Operand 3: Character scalar (fixed-length). Operand 4-6 U I I I UC [4-6] Character variable scalar (fixed-length). Branch Form- Branch 1 Operand 3 Subtrahend I point, instruction pointer, relative instruction number, or absolute instruction , Indicator Form- Numeric variable scalar or character variable scalar. • Short forms Op Code SUBLCS (Hex) Extender Operand Operand 2 1 Indicator options Difference/Minuend Subtrahend Indicator targets Branch options Difference/Minuend Subtrahend Branch targets 1927 SUBLCBS 1 D27 Operand 1: Operand 2: Operand 3-5: Character variable scalar (fixed-length). Character scalar (fixed-length). Branch Form- Branch U lUd 1 1 * 1 1 [3-5] Subtrahend 1127 SUBLCIS Operand Difference/Minuend point, instruction pointer, relative instruction number, or absolute instruction , Indicator Form-Numeric variable scalar or character variable scalar. Description: The unsigned binary value of the subtrahend operand is subtracted from the unsigned binary value of the minuend operand, and the result is placed in the difference operand. Operands 1, 2, and invalid length (hex 3 must be the same length; otherwise, the Create Program instruction signals an 2A0A) exception. The subtraction operation is performed as though the ones complement of the second operand and low-order 1 -bit were added to the first operand. Chapter 2. Computation and Branching Instructions a 2-220 Subtract Logical Character (SUBLC) then placed (left-adjusted) into the receiver operand with truncating or padding taking place on the right. The pad value used in this instruction is a byte value of hex 00. The result value is operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, If parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. Resultant Conditions: logical difference of the character scalar The • Zero with carry out of the high-order • Not-zero with carry • Not-zero with no carry. bit operands is: position Exceptions Operands 06 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X Addressing 01 08 Space addressing violation Argument/Parameter 01 10 Parameter reference violation Damage Encountered 04 System object damage state 44 1C Partial system object damage Machine-Dependent Exception 03 Machine storage 20 22 limit X exceeded Machine Support 02 Machine check X 03 Function check X Object Access 01 Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X X 08 object compressed 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2C Other 1 Exception X X X X X X Program Execution 04 Invalid branch target 2E Resource Control Limit Chapter 2. Computation and Branching Instructions 2-221 Subtract Logical Character (SUBLC) Operands Exception 1 01 32 User Profile storage limit 3 Other X Scalar Specification XXX XXX 01 Scalar type invalid 02 Scalar attributes Invalid 36 2 exceeded Space Management 01 Space Extension/Truncation X Chapter 2. Computation and Branching Instructions 2-222 Subtract Numeric (SUBN) Subtract Numeric (SUBN) Operand 3 Subtrahend Operand Difference Operand Minuend Difference Minuend Subtrahend Branch options Difference Minuend Subtrahend Branch targets Branch options Difference Minuend Subtrahend Branch targets SUBNI Indicator Difference Minuend Subtrahend Indicator targets 1847 options Difference Minuend Subtrahend Indicator targets Op Code SUBN Operand Extender (Hex) 1 2 [4-7] 1047 SUBNR 1247 SUBNB 1C47 SUBNBR E47 1 SUBNIR 1 Indicator A47 options Operand 1: Numeric variable Operand 2: Numeric scalar. Operand 3: Numeric scalar. Operand 4-7: 9 Branch Form - Branch number. • Indicator scalar. point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Short forms Op Code SUBNS (Hex) Operand Difference/Minuend Operand 2 Subtrahend Difference/Minuend Subtrahend Branch options Difference/M nuend Subtrahend Branch targets Branch options Difference/Minuend Subtrahend Branch targets Indicator options Difference/Minuend Subtrahend Indicator targets Indicator options Difference/Minuend Subtrahend Indicator targets Operand Extender 1 [3-6] 1147 SUBNSR 1347 SUBNBS 1 D47 SUBNBSR 1 i F47 SUBNIS 1947 SUBNISR 1 B47 Operand 1: Numeric variable scalar. Chapter 2. Computation and Branching Instructions 2-223 Subtract Numeric (SUBN) Operand 2: Operand 3-6: Numeric scalar. • Branch Form-Branch number. • Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable The Difference Description: Operands can have is number, or absolute instruction scalar. the result of subtracting the Subtrahend from the Minuend. floating-point, packed or zoned decimal, signed or unsigned binary type. Source operands are the Minuend and Subtrahend. The receiver operand If operands have different types, is the Difference. source operands, Minuend and Subtrahend, are converted according to the following rules: 1. If any one of the operands has floating point type, source operands are converted to floating point type. 2. Otherwise, if any one of the operands has zoned or packed decimal type, source operands are converted to packed decimal. 3. Otherwise, the binary operands are converted to a logically treated as signed binary(4) scalars. like type. Note: unsigned binary(2) scalars are Minuend and Subtrahend are subtracted according to their type. Floating point operands are subtracted using floating point subtraction. Packed decimal operands are subtracted using packed decimal subtraction. Unsigned binary subtraction is used with unsigned binary operands. Signed binary operands are subtracted using two's complement binary subtraction. Better performance can be obtained if all operands have the same type. Signed and unsigned binary subtractions execute faster than either packed decimal or floating point subtractions. Decimal operands used in floating-point operations cannot contain more than 15 total digit positions. For a decimal operation, alignment of the assumed decimal point takes place by padding with 0's on the right end of the source operand with lesser precision. Floating-point subtraction uses exponent binary point nent to the is comparison and significand subtraction. Alignment of the necessary, by shifting the significand of the value with the smaller expoThe exponent is increased by one for each binary digit shifted until the two expo- performed, right. if nents agree. The operation uses the length and the precision of the source and receiver operands rate results. Operations performed in decimal are limited to 31 decimal to calculate accu- digits in the intermediate result. The subtract operation The is performed according to the rules of algebra. result of the operation is copied into the difference operand. If this operand is not the same type performing the operation, the resultant value is converted to its type. If necessary, the resultant value is adjusted to the length of the difference operand, aligned at the assumed decimal as that used in point of the difference operand, or both before being copied to icant digits are truncated on the left it. For fixed-point operation, end of the resultant value, a size (hex OCOA) exception if is signif- signaled. For the optional round form of the instruction, specification of a floating-point receiver operand is invalid. Chapter 2. Computation and Branching Instructions 2-224 Subtract Numeric (SUBN) For floating-point operations involving a fixed-point receiver off the left end field, if nonzero would be truncated OCOC) exception is sig- digits of the resultant value, an invalid floating-point conversion (hex naled. For a floating-point difference operand, if the exponent of the resultant value is either too large or too small to be represented in the difference field, the floating-point overflow (hex 0C06) or the floatingpoint underflow (hex 0C07) exception If is signaled. a decimal to binary conversion causes a size (hex contains the correct truncated result only if OCOA) exception to be signaled, the binary value the decimal value contains 15 or fewer significant nonfractional digits. Size exceptions can be inhibited. The following are Limitations: limits that apply to the functions performed by this instruction. If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. Resultant Conditions • Positive-The algebraic value of the numeric scalar difference • Negative-The algebraic value of the numeric scalar difference 8 Zero-The algebraic value of the numeric scalar difference 8 Unordered-The value assigned a floating-point difference operand is is is positive. negative. zero. is NaN. Exceptions Operands 1 2 3 [4,5] X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X 02 Decimal data X X 03 Decimal point alignment X X X X Exception 06 Addressing 01 08 Space addressing violation Argument/Parameter 01 0C Other Parameter reference violation Computation 06 Floating-point overflow X 07 Floating-point underflow X 09 Floating-point invalid operand 0A Size X 0C Invalid floating-point conversion X 0D Floating-point inexact result X Chapter 2. X Computation and Branching Instructions 2-225 Subtract Numeric (SUBN) Operands Exception 10 1 Damage Encountered 04 System object 44 1C Partial damage 2 Other 3 [4, 5] XXX XXX state system object damage X X Machine-Dependent Exception 03 Machine storage limit exceeded 20 22 X Machine Support 02 Machine check X 03 Function check X Object Access XXX XXX XXX XXX XXX 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2C Program Execution 04 Invalid branch target 2E Resource Control Limit 01 36 X User Profile storage limit exceeded X Space Management 01 Space Extension/Truncation X Chapter 2. Computation and Branching Instructions 2-226 Test and Replace Characters (TSTRPLC) Test and Replace Characters (TSTRPLC) Op Code Operand (Hex) Operand 2 Replacement 1 Receiver 10A2 Operand /: Character variable scalar. Operand 2: Character scalar. Description: right. Any The character byte to the left string value represented by operand of the leftmost byte which has a value is 1 in tested byte by byte from left the range of hex FI to hex F9 to is assigned a byte value equal to the leftmost byte of operand 2. Both operands must be character strings. Only the first character of the replacement string is used in the operation. The operation stops when the first nonzero zoned decimal receiver operand have been replaced. digit is found or when all characters of the Exceptions Operands 06 2 X X 02 Boundary alignment X X 03 Range X X 06 Optimized addressability invalid X X X X X X X X X X Addressing 01 08 Space addressing Parameter reference violation Damage Encountered 04 System object 44 1C Partial damage 22 state system object damage Machine-Dependent Exception 03 Machine storage 20 violation Argument/Parameter 01 10 limit X exceeded Machine Support 02 Machine check X 03 Function check X Object Access 01 Object not found X X 02 Object destroyed X X 03 Object suspended X X X 08 object compressed 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Other 1 Exception X X X X Resource Control Limit Chapter 2. Computation and Branching Instructions 2-227 Test and Replace Characters (TSTRPLC) Operands Exception 01 36 1 User Profile storage limit Other 2 exceeded X Space Management 01 Space Extension/Truncation X Chapter 2. Computation and Branching Instructions 2-228 Test Bit in String (TSTBTS) Test Bit in String (TSTBTS) Op Code (Hex) TSTBTSB Operand Operand 3 Extender Branch options Operand Source Offset Branch targets Indicator options Source Offset Indicator targets 1 2 [4] 1C0E TSTBTSI 180E Operand 1: Operand 2: Operand 3: Character scalar (fixed length) or numeric scalar. Binary scalar. number, or absolute instruction • Branch Form- Branch number. » Indicator Form- Numeric variable scalar or character variable scalar. Description: bit is bit of the source operand as indicated by the offset operand to determine if the set or not set. Based on the • Tests the point, instruction pointer, relative instruction test, the resulting condition is used with the extender Transfer control conditionally to the instruction indicated in field to either one of the branch target operands (branch form), 3 Assign a value to each of the indicator operands (indicator form). The source operand can be character or numeric. The leftmost bytes of the source operand are used in the operation. The source operand is interpreted as a bit string with the bits numbered left to right from 0 to the total number of bits in the string minus one. The offset operand indicates which cating the leftmost an if bit of the source operand is to be tested, with a offset of zero indiof the leftmost byte of the source operand. offset value less than (hex 3203) exception bit is zero or beyond the length of the string is specified a scalar value invalid signaled. Resultant Conditions The selected • Zero: • One: The selected of the bit bit of the bit string bit string source operand source operand is is zero. one. Exceptions Operands 1 2 3 [4] X X X 02 Boundary alignment violation X X X 03 Range X X X 06 Optimized addressability invalid X X X Exception 06 Addressing 01 08 Other Spacing addressing violation Argument/parameter Chapter 2. Computation and Branching Instructions 2-229 Test Bit in String (TSTBTS) Operands XXX Exception 01 10 1 Parameter reference violation 44 Partial damage state X system object damage X Machine-dependent exception 03 Machine storage limit exceeded 20 22 X Machine support 02 Machine check X 03 Function check X Object access XXX XXX XXX XXX 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control exceeded X Scalar specification 01 XXX Scalar type invalid 03 Scalar value invalid 36 X limit 01 user profile storage limit 32 Other 3 [4] Damage encountered 04 System object 1C 2 X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-230 Test Bits Under Test Bits Under Op Code Mask (TSTBUM) Mask (TSTBUM) (Hex) TSTBUMB Extender Branch options Operand Source Operand Mask Indicator options Source Mask 1 Operand 2 3 [4, 5] Branch targets 1C2A TSTBUMI Indicator targets 182A Operand 1: Operand 2: Operand 3 Character variable scalar or numeric variable scalar. Character scalar or numeric scalar. [4, 5] • Branch Form-Instruction number, • Indicator Description: bit number, branch Form-Numeric variable scalar or character variable Selected bits point, or instruction pointer. scalar. from the leftmost byte of the source operand are tested to determine their values. Based on the 8 relative instruction test, the resulting condition is used with the extender Transfer control conditionally to the instruction indicated in field to: one of the branch target operands (branch form). • Assign a value to each of the indicator operands (indicator form). The source and the mask operands can be character or numeric. The leftmost byte of each of the operands is used in the operands. The operands are interpreted as bit strings. The testing is performed bit by bit with only those bits indicated by the mask operand being tested. A 1-bit in the mask operand specifies that the corresponding bit in the source value is to be tested. A 0-bit in the mask operand specifies that the corresponding bit in the source value is to be ignored. The selected bits of the bit string source operand are all zeros, all ones, or mixed ones and zeros. A mask operand of all zeros causes a zero resultant condition. Resultant Conditions: Exceptions Operands 06 2 3 [4, 5] X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X X X X X X X Addressing 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object 44 1C Other 1 Exception partial damage state system object damage Machine-dependent exception Chapter 2. Computation and Branching Instructions 2-231 Test Bits Under Mask (TSTBUM) Operands Exception 03 machine storage 20 22 1 limit 02 machine check X 03 function check X Object access XXX XXX XXX XXX XXX 03 object suspended 08 object compressed Pointer specification 01 pointer does not exist 02 pointer type invalid Resource control X limit 01 user profile storage limit 36 X Program execution 04 branch target invalid 2E Other Machine support 02 object destroyed 2C 3 [4, 5] X 01 object not found 24 2 exceeded exceeded X Space management 01 space extension/truncation X Chapter 2. Computation and Branching Instructions 2-232 Translate (XLATE) Translate (XLATE) Op Code Operand (Hex) 1094 Operand 1 Receiver Operand /: Character variable scalar. Operand 2: Character scalar. Operand 3: Character scalar or Operand 4: Character scalar. Description: and placed Operand 4 Replacement Position null. Selected characters ferent encoding Operand 3 2 Source in the string value of the source operand are translated into a dif- the receiver operand. The characters selected for translation and the in character values they are translated to are indicated by entries in the position and replacement strings. All the operands must be character strings. The source and receiver values must be of the same length. The position and replacement operands can 256-character string is used, ranging The operation begins with all in differ in length. If operand 3 a is null, value from hex 00 to hex FF (EBCDIC collating sequence). the operands left-adjusted and proceeds character by character, from to right until the character string value of the receiver operand is left completed. Each character of the source operand value is compared with the individual characters in the position operand. If a character of equal value does not exist in the position string, the source character is placed unchanged in the receiver operand. If a character of equal value is found in the position string, the corresponding character in the same relative location within the replacement string is placed in the receiver operand as the source character translated value. If the replacement string is shorter than the position string and a match of a source to position string character occurs for which there is no corresponding replacement character, the source character is placed unchanged in the receiver operand. If the replacement string is longer than the position string, the rightmost excess characters the translation operation because they have no corre- of the replacement string are not used in sponding position string characters. rence (leftmost) is used. a character If in the position string is duplicated, the first occur- If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable. The receiver, source, position, and replacement operands can be variable length substring compound operands. Substring operand references that allow for a null substring reference (a length value of zero) specified for all of the operands on this instruction. The may be effect of specifying a null substring reference replacement operands is that the source operand is copied to the receiver The effect of specifying a null substring reference for both the receiver and the source operands (they must have the same length) is that no result is set. for either the position or with no change in value. Exceptions Operands Exception 06 1 2 3 4 Other Addressing Chapter 2. Computation and Branching Instructions 2-233 Translate (XLATE) Operands Exception 1 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X X X X X X X X X X X 01 08 violation Other Argument/Parameter 01 0C Space addressing Parameter reference violation Computation 08 Length conformance 10 Damage Encountered 04 System object 44 1C Partial damage system object damage Machine-Dependent Exception 03 Machine storage 20 22 state limit exceeded Machine Support 02 Machine check X 03 Function check X Object Access found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 Object not 08 object compressed 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 36 User Profile storage limit exceeded Space Management 01 Space Extension/Truncation Chapter 2. Computation and Branching Instructions 2-234 Translate with Table (XLATEWT) Translate with Table Op Code (XLATEWT) Operand (Hex) Operand 1 Receiver 109F Operand 1 Operand 2: Character scalar. Operand 3: Character scalar. Operand 2 Source 3 Table Character variable scalar. : Description: the receiver. The source characters are translated under control of the translate table and placed in The operation begins with the leftmost character of operand 2 and proceeds character- by-character, left-to-right. Characters are translated as follows: • • The source character used as an is The character contained to the receiver in the in same offset and added to the location of operand the offset location is the translated character. 3. This character relative position as the original character in the source is copied string. If operand 3 is less than 256 bytes long, the character in the source may specify an offset beyond the end of operand 3. If operand 2 is longer than operand 1, then only the leftmost portion of operand 2, equal to the length of operand 1, is translated. If operand 2 is shorter than operand 1, then only the leftmost portion of operand 1, equal to the length of operand 2, is changed. The remaining portion of operand 1 is unchanged. If operand 1 overlaps with operand 2 and/or 3, the overlapped operands are updated for every character translated. The operation proceeds from example shows the the Hex same left to right, one character at a time. The following operands translate operation. Operands 1, 2, and 3 have with a value of hex 050403020103, results of an overlapped coincident character string 050403020103-Initial value Hex 030403020103-After the 1st character is translated Hex 030103020103-After the 2nd character is translated Hex 0301 020201 03-After the 3rd character is translated Hex 0301 020201 03-After the 4th character is translated Hex 0301 020201 03-After the 5th character is translated Hex 030102020102-After the 6th character, the final result Note that the instruction does not use the length specified for the table operand to constrain access of the bytes addressed by the table operand. If operand 3 is less than 256 characters long, and a source character specifies an offset beyond the end of operand 3, the result characters are obtained from byte locations in the space following operand If that portion of the space is not currently allocated, a space addressing exception is signaled. 3. If operand 3 is a constant with a length less than 256, source characters specifying offsets greater than or equal to the length of the constant are translated into unpredictable characters. All of the operands support variable length substring compound Chapter 2. scalars. Computation and Branching Instructions 2-235 Translate with Table (XLATEWT) Substring operand references that allow for a null substring reference (a length value of zero) may be specified for all of the operands on this instruction. Specifying a null substring reference for the table operand does not affect the operation of the instruction. In this case, the bytes addressed by the table operand are still accessed as described above. This is due to the definition of the function of this instruction which does not use the length specified for the table operand to constrain access of the bytes addressed by the table operand. The effect of specifying a null substring reference for either or both of the receiver and the source operands is that no result is set. Exceptions Operands Exception 06 1 01 Space addressing violation 02 Boundary alignment 03 Range 06 Optimized addressability invalid 08 Argument/Parameter 01 10 3 Parameter reference violation Partial system object damage X Machine-Dependent Exception 03 Machine storage limit exceeded 20 22 X Machine Support 02 Machine check X 03 Function check X XXX XXX XXX XXX Object Access 02 Object destroyed 03 Object suspended 08 object compressed 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 32 User Profile storage limit exceeded X XXX Scalar Specification 01 Scalar type invalid 36 Other Damage Encountered 44 1C 2 XXX XXX XXX XXX XXX Addressing Space Management 01 Space Extension/Truncation X Chapter 2. Computation and Branching Instructions 2-236 Translate with Table and Translate with Table and DBCS DBCS Skip (XLATWTDS) Skip (XLATWTDS) I | Op Code Operand (Hex) Operand 1 Operand 2 Length Target 1077 3 Table j | | | Operand 1: Character variable scalar Operand 2: Binary(4) scalar. Operand 3: Character scalar — (fixed length). (fixed length). ILE access XLATWTDS ( var target var length var table : : : aggregate unsigned binary, aggregate ; ) Description: The simple (single byte) characters in the Target are translated under control of the Operand 2. The extended (double byte) character portions of bypassed and not translated. the target are The operation begins with the leftmost character of operand 1 and proceeds character-by-character, left-to-right, skipping over any Double byte character (DBCS) data portions. translate table, for the length defined by The target, acter (SO Operand = 1, should have double byte character data surrounded by a hex 0E) and a shift in control character (Sl= hex OF). Once a The operation ered, the translating of single byte characters halts. character-by-double byte character until a SI character is will SO shift out control char- character encount- is then proceed double byte encountered. This shift in character is then used to restart the translating of single byte characters. The length operand, Operand 2, is the number of bytes and must contain a value between For length values outside this range a scalar value invalid (hex 3203) exception is 1 and 32767. signaled. Single byte characters are translated as follows: • The target character • The character contained used as an is offset Operand at the offset location of acter replaces the original character The and added to the location of Operand in 3 is 3. the translated character. This char- the target. example shows the step-by-step results of this translate operation. The translate table example has the following hex value: C3D406C5D504C1C2C4C5C6C7C8C9C1C6 following for this Hex 05040ED2D2E1E10F03 - Initial Hex 04040ED2D2E1E10F03 - After the 1st character target value is Hex 04D50ED2D2E1E10F03 - After the 2nd character Hex 04D50ED2D2E1E10F03 - SO Hex 04D50ED2D2E1E10F03 - Resume Hex 04D50ED2D2E1E10FC5 - translated is translated character encountered, skip the DBCS portion translating after SI control character Translate 9th character Chapter 2. Computation and Branching Instructions 2-237 Translate with Table and | | | | | | | | | | | Hex 04D50ED2D2E1E10FC5 - DBCS Skip (XLATWTDS) Final target value The translate table, Operand 3, is assumed to be 256 bytes long. If the table is less than 256 characand a target character specifies an offset beyond the end of the table, the resultant characters are obtained from byte locations in the space following translate table. If that portion of the space is not currently allocated, a space addressing (hex 0601) exception is signaled. ters long, This operation only translates the target string and does not validate the Double byte portions of the For example, if a DBCS portion of the target string is preceded by the Shift Out control character, but missing the closing Shift In character, then an invalid extended character data (hex 0C12) exception will NOT be signaled. However, the Copy Extended Characters Left-Adjusted With Pad target. (CPYECLAP) instruction can be used to validate extended character data, if necessary. Exceptions Operands Exception 06 1 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X X X X 01 08 Parameter reference violation Damage encountered 44 1C Spacing addressing violation Argument/parameter 01 10 Partial system object damage 22 limit exceeded X Machine support 02 Machine check X 03 Function check X Object access 02 Object destroyed X X X 03 Object suspended X X X 08 object compressed 24 X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X exceeded X Scalar type invalid X 03 Scalar value invalid 36 X Scalar specification 01 [ X limit 01 user profile storage limit 32 X Machine-dependent exception 03 Machine storage 20 Other Addressing X X X Space management Chapter 2. Computation and Branching Instructions 2-238 Translate with Table and DBCS Skip (XLATWTDS) Operands Exception 1 2 3 Other | 01 X space extension/truncation | Chapter 2. Computation and Branching Instructions 2-239 Trim Length (TRIML) Trim Length (TRIML) Op Code Operand (Hex) 10A7 1 Receiver length Operand 1: Numeric variable Operand 2: Character scalar. Operand 3: Character(l) scalar. Operand 2 Operand 3 Source Trim character string scalar. The operation determines the resultant length of operand 2 after the character specified by operand 3 has been trimmed from the end of operand 2. The resulting length is stored in operand 1. Operand 2 is trimmed from the end as follows: if the rightmost (last) character of operand 2 is equal to the character specified by operand 3, the length of the trimmed operand 2 string is reduced by 1. This operation continues until the rightmost character is no longer equal to operand 3 or the Description: trimmed length is zero. If operand used as the trim character. Operands 2 and 3 3 is longer than one character, only the first (leftmost) character is are not changed by this instruction. Exceptions 12 Operands Exception 06 Addressing 01 Space addressing 03 Range 06 Optimized addressability invalid Argument/Parameter 01 0C Parameter reference violation Computation 0A Size 10 X Damage Encountered 44 1C Partial system object damage X Machine-Dependent Exception 03 Machine storage limit exceeded 20 22 Other XXX XXX XXX XXX XXX violation 02 Boundary alignment 08 3 X Machine Support 02 Machine check X 03 Function check X Object Access XXX XXX XXX 01 Object not found 02 Object destroyed 03 Object suspended 08 object compressed Chapter 2. Computation and Branching Instructions 2-240 Trim Length (TRIMl) Operands Exception Pointer Specification 24 01 Pointer does not 1 User Profile storage limit X exceeded XXX Scalar Specification 01 Scalar type invalid 36 Other Resource Control Limit 01 32 3 XXX XXX exist 02 Pointer type invalid 2E 2 Space Management 01 X Space Extension/Truncation Chapter 2. Computation and Branching Instructions 2-241 Verify (VERIFY) Verify (VERIFY) Op Code (Hex) VERIFY 10D7 Extender VERIFYB 1CD7 VERIFYI 18D7 Operand Operand 2 Operand Receiver Source Class Branch options Receiver Source Class Branch targets Indicator Receiver Source Class Indicator targets 1 [4-5] options Operand 1: Binary variable scalar or binary array. Operand 2: Character scalar. Operand 3: Character scalar. Operand 4-5 : • Branch Form - Branch number. * Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. Each character of the source operand character string value the valid characters indicated in the class operand. Description: among Operand 3 is checked to verify that it is The operation begins at the left end of the source string and continues character by character, from left Each character of the source value is compared with the characters of the class operand. If a match for the source character exists in the class string, the next source character is verified. If a match for the source character does not exist in the class string, the binary value for the relative to right. location of the character within the source string If the receiver operand receiver operand is is The operation continues 0. If first placed in the receiver operand. occurrence of an many occurrences invalid character is noted. If the as there are elements in the array are noted. no more occurrences of invalid characters can be noted or until the end When the second condition occurs, the current receiver value is the receiver operand is an array, all its remaining entries are set to 0's. of the source string set to a scalar, only the an array, as is is until encountered. The source and class operands can be variable length substring compound operands. Substring operand references that allow for a null substring reference (a length value of zero) may be operands 2 and 3. The effect of specifying a null substring reference for the class operand when a nonnull string reference is specified for the source is that all of the characters of the specified for source are considered invalid. In this case, the receiver is accordingly set with the offset(s) to the bytes of the source, and the instruction's resultant condition is positive. The effect of specifying a null substring reference for the source operand (no characters to verify) is that the receiver is set to zero and the instruction's resultant condition Resultant Conditions: operand is is zero regardless of what The numeric value(s) an array, the resultant condition of the receiver is 0 if all is is specified for the class operand. either 0 or positive. elements are When the receiver 0. Exceptions Chapter 2. Computation and Branching Instructions 2-242 Verify (VERIFY) Operands Exception 06 1 Addressing X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X damage X X X X system object damage X X X X 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object 44 1C Other 2 partial Machine-dependent exception 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X Object access X X X 02 object destroyed X X X 03 object suspended X X X X X X X X X 01 object not found 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution 04 branch target invalid 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 space extension/truncation Chapter 2. Computation and Branching Instructions 2-243 Date/Time/Timestamp Instructions Chapter 3. Date/Time/Timestamp Instructions are This chapter describes all instructions used for date, time, and timestamp use. These instructions "Instruction Appendix A, see instructions, the all of summary alphabetic For an in alphabetic order. Summary” 3-3 External Data Formats Timestamp Concepts 3-3 Compute Date Duration (CDD) Compute Time Duration (CTD) Compute Timestamp Duration (CTSD) 3-13 Convert Date (CVTD) Convert Time (CVTT) Convert Timestamp (CVTTS) 3-22 Decrement Date (DECD) Decrement Time (DECT) Decrement Timestamp (DECTS) 3-31 Date, Time, and . . . . . . . © Copyright IBM Corp. 1991, 1993 3-19 3-25 3-28 3-35 3-38 . . . 3-42 Increment Date (INCD) Increment Time (INCT) increment Timestamp (INCTS) 3-16 3-46 3-49 . . . . 3-1 Date/Time/Timestamp instructions Chapter 3. Date/Time/Timestamp Instructions 3-2 Date/Time/Timestamp Instructions External Data Formats For support of date, time, and timestamp, the external data format that Associated with this character string will be a data definitional attribute is used is a character string. (DDAT) that describes all list the attributes of the string. The attributes that are associated with the character string are as follows: « Calendar » Era table. » Format code. • Date separator type. • Time separator • Time zone. » Month • Year • Century. table. type. definition. definition. Date, Time, and Timestamp Concepts Data Definitions is a 4 byte binary value. The DDAT number must reference or be set to zero which implies internal format. The fixed length, trailing blanks are NOT allowed. DATE Date data type. The internal format a DDAT with an internal DATE format code internal format is Time data type. The internal format is six numbers packed into a three byte value. There is no code or be set to sign nibble. The DDAT number must reference a DDAT with an internal TIME format blanks are NOT allowed. trailing length, fixed is format The internal format. zero which implies internal TIME. Timestamp data type. The internal format of a Timestamp is a ten byte composite value. The composite is two numbers one for date and time respectfully. The date and time numbers have the same encoding as the date and time data types, with an exception to the time number. The time number has an additional 3 bytes for a six packed digit microsecond value. The DDAT number must reference a DDAT with an internal Timestamp format code or be set to zero which implies internal TIMESTAMP. format. The internal format is fixed length, trailing blanks are NOT allowed. Character data type with a DDAT referenced. The DDAT number must reference a DDAT supported formats, with a valid date format code. The character string format must match one of the which can string character the of bytes of number the trailing blanks are allowed. The length is PseudoDATE. include trailing blanks. Character data type with a DDAT referenced. The DDAT number must reference a DDAT formats, with a valid time format code. The character string format must match one of the supported can string which character of the bytes of number the trailing blanks are allowed. The length is PseudoTIME. include trailing blanks. Character data type with a DDAT referenced. The DDAT number must reference with a valid timestamp format code. The character string format must match one of the sup- PseudoTIMESTAMP. a DDAT Chapter 3. Date/Time/Timestamp Instructions 3-3 Date/Time/Timestamp Instructions ported formats, trailing blanks are allowed. The length which can include is the number of bytes of the character strina trailing blanks. DATE DURATION. Packed decimal data type with a DDAT DDAT number is set to reference a DDAT with a valid date referenced. The length must be duration format code. TIME DURATION. Packed decimal data type with a DDAT referenced. The length must be DDAT number must reference a DDAT with a valid time duration format code. TIMESTAMP DURATION. Packed decimal data The DDAT number must reference a DDAT with 8,0. The 6,0. The type with a DDAT referenced. The length must be a valid timestamp duration format code. 20,6. DATE LABEL DURATIONS Packed decimal data type with a DDAT referenced. The length must be 15,0. The DDAT number must reference a DDAT with a valid date label duration format code. TIME LABEL DURATIONS. Packed decimal data type with a DDAT referenced. The length must be 15,0. The DDAT number must reference a DDAT with a valid time label duration format code. TIMESTAMP LABEL DURATIONS. Packed decimal data type with a DDAT referenced. The be 15,0. The DDAT number must reference a DDAT with a valid timestamp label duration length must format code. Data Conversion The following table describes the possible conversions Source Operand for date/time data. Result Operand DATE DATE TIME TIME or PseudoTIME TIMESTAMP TIMESTAMP PseudoDATE DATE PseudoTIME TIME PseudoTIMESTAMP TIMESTAMP PseudoDATE or PseudoTIMESTAMP PseudoDATE or or or PseudoTIME or PseudoTIMESTAMP Arithmetic For all Date/Time arithmetic, Increment, Decrement, and Compute, there must be specified between operand 1, operand 2, and the result. DDAT number DDATs DDATs when both DDAT numbers are 0 or both they reference are byte for byte identical. are equivalent DDAT numbers at least one non-zero are non-zero and the End of month adjustment can only be specified in conjunction with Date and Timestamp arithmetic that involves the incrementing and decrementing of Dates or Timestamps. When end of month adjustment is specified, there must be at least one non-internal format specified for operand 1, operand 2, or the result. When end of month adjustment is not specified all durations must reference a DDAT that specifies a year and month definition other than zero. Chapter 3. Date/Time/Timestamp Instructions 3-4 Date/Time/Timestamp Instructions Data Definitional Attribute Template The • following describes the Data Definitional Attribute Template (DDAT). Char(112-n) Data definitional attribute template (optional) be used can template one template, requires a (repeated for each operand/field that operands/fields that have the same attributes) - DDAT length — Format code - — — UBin(2) (ignored) UBin(2) Char(2) Separator definition - Date separator type Char(1) - Time separator type Char(1) — Time zone Char(4) definition - Hour zone UBin(2) - Minute zone UBin(2) Duration definitions Char(4) - Month - Year 1 UBin(2) definition UBin(2) definition Char(8) Century definition - Current century UBin(4) - Century division UBin(4) — Calendar table - Reserved (binary - Era table template Char(50-n) — Calendar table template Char(18-n) UBin(4) offset Char(6) 0) The following table describes the operand type and DDAT field associations. Chapter 3. Date/Time/Timestamp Instructions 3-5 Date/Time/Timestamp Instructions Operand Type Format Code Date Sepa- Time rator rator Sepa- Time Zone Month Year Defi- Defi- nition nition Century Era Table Calendar Table Date REQ REQ INV INV INV INV REQ REQ REQ Time REQ INV REQ REQ INV INV INV INV INV Timestamp REQ REQ REQ REQ INV INV REQ REQ REQ Pseudo Date REQ REQ INV INV INV INV REQ REQ REQ Pseudo Time REQ INV REQ REQ INV INV INV INV INV Pseudo Timestamp REQ REQ REQ REQ INV INV REQ REQ REQ Date Dura- REQ INV INV INV EMA EMA INV INV INV REQ INV INV INV INV INV INV INV INV REQ INV INV INV EMA EMA INV INV INV REQ INV INV INV EMA EMA INV INV INV REQ INV INV INV EMA EMA INV INV INV Day Label Duration REQ INV INV INV EMA EMA INV INV INV Hour Label REQ INV INV INV INV INV INV INV INV REQ INV INV INV INV INV INV INV INV REQ INV INV INV INV INV INV INV INV REQ INV INV INV INV INV INV INV INV tion Time Duration Timestamp Duration Year Label Duration Month Label Duration Duration Minute Label Duration Second Label Duration Micro- second Label Duration Notes: REQ The DDAT field is INV The DDAT field is invalid EMA The DDAT field is wise the The DDAT field required and the value must be non-zero. and the value must be zero. required to have a zero value for end of month adjustment arithmetic. Othervalue is required to be non-zero. length the length of the DDAT in bytes. This field is ignored by the instruction. The following describes the format code The formats are use to define the representation or across the Ml. They also imply the length of the data. interpreta- tion of data Chapter 3. Date/Time/Timestamp instructions 8-6 Date/Time/Timestamp Instructions Format Type Format Minimum Maximum Minimum Maximum Code Input Input Length Length Output Length Output Length USA date Hex 0001 8 n 10 n USA time Hex 0002 7 n 8 n ISO date Hex 0003 8 n 10 n ISO time Hex 0004 4 n 8 n EUR date Hex 0005 8 n 10 n EUR time Hex 0006 4 n 8 n JIS date Hex 0007 8 n 10 n JIS time Hex 0008 4 n 8 n SAA timestamp Hex 0009 16 n 26 n System internal date Hex 000A 4 4/n# 4 4/n System internal time Hex 000B 3 3/n# 3 3/n# System internal Hex 000C 10 10/n 10 10/n# timestamp # # Labeled duration YEAR Hex 000 D 15,0 15,0 15,0 15,0 Labeled duration MONTH Hex 000E 15,0 15,0 15,0 15,0 Labeled duration DAY Hex 000F 15,0 15,0 15,0 15,0 Labeled duration HOUR Hex 0010 15,0 15,0 15,0 15,0 Hex 001 15,0 15,0 15,0 15,0 Labeled duration MINUTE Labeled duration SECOND Hex 0012 15,0 15,0 15,0 15,0 Labeled duration MICROSECOND Hex 0013 15,0 15,0 15,0 15,0 Date duration Hex 0014 8,0 8,0 8,0 8,0 Time duration Hex 0015 6,0 6,0 6,0 6,0 Timestamp duration Hex 0016 20,6 20,6 20,6 20,6 "MMDDYY Hex 0017 6 n 6 n ‘DDMMYY Hex 0018 6 n 6 n ‘YYMMDD Hex 0019 6 n 6 n "YYDDD Hex 001 5 n 5 n "HHMMSS Hex 001 6 n 6 n IMPI clock Hex 00 1C 8 8 8 8 "YYYYDDD Hex 001 7 n 7 n "YYYYMMDDhhmmss Hex 00 IE 14 n 14 n "Unknown date Hex 001 4 n F n "Unknown time Hex 0020 3 n F n "Unknown timestamp Hex 0021 10 n F n Chapter 3. Date/Time/Timestamp Instructions 3-7 Date/Time/Timestamp Instructions Format Type Format Preferred Search Character Packed Code Format List data type decimal data type USA date Hex 0001 Y Y Y N USA time Hex 0002 Y Y Y N ISO date Hex 0003 Y Y Y N ISO time Hex 0004 Y Y Y N EUR date Hex 0005 Y Y Y N EUR Hex 0006 Y Y Y N JIS date Hex 0007 Y Y Y N JIS time Hex 0008 Y Y Y N SAA timestamp Hex 0009 Y Y Y N System internal date Hex 000A Y N Y N System internal time Hex 000B Y N Y N System internal Hex 000C Y N Y N time timestamp Labeled duration YEAR Hex 000D N Y Labeled duration MONTH Hex 000E N Y Labeled duration DAY Hex 000 N Y Labeled duration HOUR Hex 0010 N Y Labeled duration MINUTE Hex 0011 N Y Labeled duration SECOND Hex 0012 N Y Labeled duration MICROSECOND Hex 0013 N Y Date duration Hex 0014 N Y Time duration Hex 0015 N Y Timestamp duration Hex 0016 N Y ’MMDDYY Hex 0017 Y N Y N ‘DDMMYY Hex 0018 Y N Y N ’YYMMDD Hex 0019 Y N Y N ’YYDDD Hex 001A Y N Y N ’HHMMSS Hex 001 Y N Y N IMPI clock Hex 001 Y N Y N ‘YYYYDDD Hex 001 Y Y Y N ’YYYYMMDDhhmmss Hex 001 Y Y Y N ’Unknown date Hex 001 Y N ’Unknown time Hex 0020 Y N ’Unknown timestamp Hex 0021 Y N Notes: 'n' - Any number which 'Y' - Allowed. 'N' - Not allowed. ' ' - is greater than minimum length. Not applicable. Chapter 3, Date/Time/Timestamp Instructions 3-8 Date/Time/Timestamp Instructions 'F' - Reference the formats '#' Date, time, and timestamp data types the length - data type the length is for this value. is fixed 4, and 10 3, respectfully. For the character variable. For further information on the SAA formats reference the SAA CPI Database Reference. The following are the descriptions of the formats, D represents days, M represents months, Y represents years, h represents hours, m represents minutes, s represents seconds and u represents microseconds. • USA - Date - MM/DD/YYYY, character string. - hh:mm AM or PM, character string. 00:00 AM or 12:00 AM is midnight. 12:00 PM Between 'hh:mm' and 'AM' or 'PM' only one one blank is allowed. - Time • Date - - Time Date - Time - hh.mm.ss, character - DD.MM.YYYY, character - hh.mm.ss, character string. string. string. string. JIS - Date - Time • YYYY-MM-DD, character EUR - • noon. ISO - • is - - YYYY-MM-DD, character hh:mm:ss, charracter string. string. SAA timestamp - Timestamp YYYY-MM-DD-hh.mm.ss.uuuuuu, character string. Leading zeros maybe omitted from the month, day, and hour part of the timestamp, and microseconds may be truncated or entirely omitted, {.10 • System - = .100000). internal format Date - Time - - 4 byte binary Scaliger 3 byte value with number each byte containing two packed decimal digits having the encoding of hhmmss. - Timestamp - 10 byte composite number, the first part being a 4 byte internal date and the second part being a 3 byte internal time, plus microseconds, a 3 byte value with each byte containing two packed decimal digits having the encoding of uuuuuu. • Labeled durations - • They are a 15,0 packed decimal data value. The keywords; YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MICROSECONDS, or the singular form of the keywords; YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MICROSECOND, are not part of the data. Date duration - Packed - • 9999, decimal MM (8,0) number having the encoding has the range 0 - 99, of YYYYMMDD, where YYYY has and DD has the range 0 - the range 0 99. Time duration - Packed decimal (6,0) number having the encoding of hhmmss, where hh has the range 0 has the range 0 - 99, and ss has the range 0 - 99. - 99, mm • Timestamp duration Chapter 3. Date/Time/Timestamp Instructions 3-9 Date/Time/Timestamp Instructions - Packed decimal (20,6) number having addition to date and time, 8 ‘MMDDYY — Date MMDDYY, character string ‘DDMMYY — Date - DDMMYY, character string *YYMMDD — Date - YYMMDD, character string - • • • • in - YYDDD, character string character string It is an 8 byte clock, bit which is used as a timestamp. *YYYYDDD Date - YYYYDDD, seven character string. Used on the DATE scalar function. ‘YYYYMMDDhhmmss ~ 8 YYYYMMDDhhmmssuuuuuu, where 999999. IMPI clock • Date ‘HHMMSS — Time - hhmmss, • - *YYDDD — • the encoding of uuuuuu has the range 0 Timestamp - YYYYMMDDhhmmss fourteen character string. ‘Unknown - Used to reference unique SAA formats. This format is used only when the format is NOT known. This format tries to find a matching format. The formats that will be scanned for are; USA, ISO, EUR, JIS, dates and times, ‘YYYYDDD (date), SAA timestamp, and ‘YYYYMMDDhhmmss timestamp. When a valid match is not found either a data, format or value, exception will be signalled. The following describes the separator definitions for date and time. The separator type is a one charcontains the separator value, for example, When the format has an implied ., /, or -. separator, the implied separator is used. For example, an ISO date, the implied separator is When the format does not have an implied separator, the implied separator is null. For example, the format ‘YYMMDD has an implied separator of null. A null separator means the units of time, year, month, day, etc..., are concatenated together. A implied separator is specified by using the value of hex '00'. A null separator is specified by using the value of hex 'FF'. A null separator is invalid for the SAA formats, USA, ISO, etc... Any other separator value overrides the implied value for the format code. acter field that The following describes the time zone definition The hour zone value is 0 to 24. GMT zone is 0. The zone to the east of zone 0 is zone 1. The zone to the east of zone 1 is zone 2, and so on. The value 24 specifies that the time is to be stored as local time and that the concept of time zones should be ignored. The value of 24 is required for storage purposes. For example, when inserting a time field into a database data space the hour zone value must be 24. A value other than 24 can be used for . retrieval purposes. The m inute zong GMT zone is 0. The zone to the west of zone 0 is zone 1. The zone to and so on. The value 60 specifies that the time is to be stored as local time and that the concept of time zones should be ignored. The value of 60 is required for storage purposes. For example, when inserting a time field into a database data space the minute zone value must be 60. A value other than 60 can be used for retrieval purposes. the west of zone value 1 is is 0 to 60. zone 2, Chapter 3. Date/Time/TImestamp Instructions 3-1 Date/Time/Timestamp Instructions definition is an integer number of days. For example 30, would specify that each month use a duration would have a constant value of 30 days. The a value of zero specifies that the calendar definition of the month should be used. The month in The year definition is an integer number of days. For example 365, would specify that each year use in a duration would have a constant value of 365 days. The a value of zero specifies that the calendar definition of the year should be used. When end of month adjustment arithmetic is being performed, the month definition and year definition must have zero values. When no end of month adjustment arithmetic is being performed, the month definition and year definition must have non-zero values. Otherwise a template value invalid (hex 3801) exception will be signaled. The century field is used to define the century when a two digit year is specified for a date. The definition is two numbers, one for current century and the other is for the century division year. The current century is a century number. The century division is a year number. The valid values for the current century are 0 - 99. The valid values for the century division are 0 - 99. The century division is included in the current century. For example, a current century of 19 and a century division of 50 would result in two digit years 00 - 49, having the values 2000 - 2049 and 50 - 99 having values 1950 1999. The calendar table offset is the number of bytes from the start of the DDAT to the start of the calendar table (described below). Era Table The era table immediately follows the The fixed portion of the DDAT. following describes the era table data. • Number • Era element (repeatable) Char(48) — Origin date UBin(4) — Era — Reserved (binary UBin(2) of table elements name Char(32) Char(12) 0) The era table is a list of elements that state what era should be used across the time line. The start of usage of a particular era is specified by the origin date. The end of usage of a particular era is terminated by the next table element. The last table element era is used until the end of the time line. The origin date is specified in the internal format. The era name is a character field. The maximum number of table entries allowed is 256. The SAA era table has one entry. The SAA origin date is January 1, 0001, Gregorian for the line. The internal format would be 1721424. The SAA name is AD, anno Domini. start of the time The SAA era in table can have only the time line specified in the one element and SAA that element must have an effective date that falls calendar table. Chapter 3. Date/Tlme/Timestamp Instructions 3-1 Date/Time/Timestamp Instructions Calendar Table The following describes the calendar table data. • Number * Calendar change element (repeatable) Char(16) - Effective date UBin(4) - Calendar type UBin(2) of table elements - Reserved UBin{2) (binary 0) Char(10) The calendar table is a list of elements that state what calendar type/algorithm should be used across line. The start of usage of a particular calendar is specified by the effective date. The effective date is specified using the internal format. This first table element represent the beginning of the time line. The end of usage of a particular calendar is terminated by the next table element. The last table element calendar must be null this indicates the end of the time line. The maximum number of table the time entries allowed is 256. The SAA calendar table has 2 entries. The first entry has a calendar type of Gregorian. The effective January 1, 0001, Gregorian for the start of the time line. The internal format would be 1721424. The second entry has a calendar type of null. The effective date is January 1, 10000, Gregorian for the end of the time line. The internal format would be 5373485. date is Multiple calendar table entries are only valid with DDATs specifying the internal date format code. The rest of format codes can only have two entries in the calendar table. The second entry must have a NULL calendar type. The following describes the encoding of the calendar types . Calendar type Calendar Null Hex 0000 Gregorian Hex 0001 Julian Hex 0002 Muslim Hex 0003 Hebrew Hex 0004 Chapter 3. Date/Time/Timestamp Instructions 3-12 Compute Date Duration (ODD) Compute Date Duration (CDD) Op Code Operand (Hex) Operand 1 Date Date duration 0424 Operand 1\ Operand 2: Character scalar. Operand 3: Character scalar. Operand 4\ Space CDD Packed decimal variable 2 1 Operand 3 Operand 4 Date 2 Instruction template scalar. pointer. ( packed decimal aggregate aggregate space pointer var date_duration var datel var date2 i ; ; nstructi on_templ ate ) Description: The date specified by operand the value of the results a duration butes for operands A negative value through 1 will in operand Operand 1. 4 defines the data definitional first operand is less than the second operand. instruction template. Char(*) — UBin(4) Instruction template size — Operand — Operand 1 data definitional attribute template number UBin{2) 2 data definitional attribute template number UBin(2) number UBin(2) attribute template Char(2) 2 length UBin(2) 3 length UBin(2) — Reserved (binary — Data definitional attribute template Char(26) 0) Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) UBin(4) list UBin(2) Char(10) 0) UBin(4) offset (repeated) data definitional attribute template (DDAT) tion of a template first Char(*) list - of in attri- 3. — Operand 3 data definitional — Reserved (binary 0) the subtracted from the date specified by operand 2 and 3 is Instruction template — Operand — Operand A place be returned when the The following describes the 9 is number is a Char(*) number the data definitional attribute template template. The valid values for this field are 1, 2, list and . that corresponds to the relative posi- For example the number 1 references 3. Chapter 3. Date/Time/Timestamp Instructions 3-13 Compute Date Duration (CDD) The DDAT for operand 1 must be valid for a date duration. The DDATs for operands 2 and 3 must be and identical. Otherwise, a template value invalid (hex 3801) exception will be sig- valid for a date naled. Operand 2 length The size of the and operand DDAT list is 3 length specified in of in number of bytes. bytes. DDATs is the count of DDATs DDATs that can be specified is 3. Tfie Ityglfrer of number are specified specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list There should be as many DDAT offsets as there are DDATs specified. The maximum to the start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the character operands will be defined by the template. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5 definitional attributes of the Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X 15 Data boundary overflow X X 16 Data format X X 17 Data value X X 18 Date boundary underflow X X X X X X X X _x X X X 01 08 10 Space addressing violation Parameter reference violation Computation Damage Encountered 04 System object 44 20 Other Argument/Parameter 01 OC 1 Addressing Partial damage state system object damage Machine Support 02 Machine check X 03 Function check X Chapter 3. Date/Time/Timestamp Instructions 3-14 Compute Date Duration (ODD) Operands Exception 22 1 2 3 4 Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 32 36 User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 Other Object Access X Space Extension/Truncation Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestarnp Instructions 3-15 Compute Time Duration (CTD) Compute Time Duration (CTD) Op Code (Hex) Operand 1 Time duration 0454 Operand 1: Operand 2: Character scalar. Operand 3: Character scalar. Operand 4: Space Operand Time 1 Packed decimal variable 2 Operand 3 Time 2 Operand 4 Instruction template scalar. pointer. ILE arrpcs 1 CTD ( var time_duration var timel var time2 packed decimal aggregate ; ; aggregate-, instruction template space pointer ) Description: The time specified by operand iS A negative value will Pla “ be returned when the 3 is subtracted from the time specified by operand 2 and ° Perand first 1 operand 0Perand is - -Snafr 4 less than the second operand. The following describes the instruction template. • Instruction template Char(*) - Instruction - Operand Operand template size data definitional attribute template number UBin(2) 2 data definitional attribute template number UBin(2) number UBin(2) ~ Operand 3 data definitional - Reserved (binary 0) - Operand - Operand UBin(4) 1 attribute template Char(2) 2 length UBin(2) 3 length UBin(2) - Reserved (binary - Data definitional attribute template A Size of the DDAT - Number DDATs - Reserved (binary - DDAT T7 jgj on the of list Char(*) list UBin(4) UBin(2) 0) Char(10) offset (repeated) UBin(4) Data definitional attribute template (repeated) Char(*) Diti ° nal attHbute of a template first Char(26) - - t 0) m f DDAT ) n^ber is a number that corresponds to the relative oosi the data definitional attribute template list. For example number template. The valid values for this field are L 1, 2, and , re,erences 3. Chapter3. Date/Time/Timestamp Instructions 3-1 Compute Time Duration (CTD) The DDAT for operand 1 must be valid for a time duration. The DDATs for operands 2 and 3 must be and identical. Otherwise, a template value invalid {hex 3801) exception will be sig- valid for a time naled. Operand 2 length The size of the and operand 3 length are specified DDAT list is specified in number of number of bytes. bytes. of DDATs is the count of DDATs DDATs that can be specified is 3. The number in specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list to the There should be as many DDAT offsets as there are DDATs specified. The maximum start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the definitional attributes of the operands. The length of the character operands will be defined by the template. For a further description of the data definitional attribute template, see “Data Definitional bute Template” on page 3-5 Attri- Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 10 Other X X X X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X 16 Data format X X 17 Data value X X X X X X X X X X X X violation Argument/Parameter Parameter reference violation Computation Damage Encountered 44 22 4 X Space addressing 04 System object damage state 20 3 02 Boundary alignment 01 0C 2 Addressing 01 08 1 Partial system object damage Machine Support 02 Machine check X 03 Function check X Object Access 01 X Object not found Chapter 3. X X X Date/Time/Timestamp Instructions 3-17 Compute Time Duration (CTD) Operands Exception 02 Object destroyed 1 2 3 4 X X X X X X X X X X X X X X X X Other | 03 Object suspended 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 32 36 Profile storage limit exceeded X Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 User Space Extension/Truncation X Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-18 Compute Timestamp Duration (CTSD) Compute Timestamp Duration (CTSD) Op Code (Hex) 043C Operand 1 Timestamp dura- Operand 2 Timestamp Operand 3 Timestamp 1 Operand 4 Instruction template 2 tion Operand 1: Packed decimal variable Operand 2: Character scalar. Operand 3: Character scalar. Operand 4: Space pointer. CTSD ( var timestamp_duration var timestampl var timestamp2 : : : nstructi on_templ ate i scalar. : packed decimal aggregate aggregate ; space pointer ; ; ) The timestamp specified by operand 3 is subtracted from the timestamp specified by and the value of the results a duration is place in operand 1. Operand 4 defines the data definitional attributes for operands 1 through 3. Description: operand A 2 negative value will be returned when the The following describes the • first operand is less than the second operand. instruction template. Instruction template Char(*) — Bin(4) Instruction template size — Operand — Operand 1 data definitional attribute template number UBin(2) 2 data definitional attribute template number UBin{2) number UBin(2) — Operand 3 data definitional — Reserved (binary 0) — Operand — Operand Char(2) 2 length UBin(2) 3 length UBin(2) — Reserved — attribute template Char(26) (binary 0) Data definitional attribute template - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of Char(*) list UBin(4) list UBin(2) Char(10) 0) offset (repeated) UBin(4) Char(*) Chapter 3. Date/Time/Timestamp Instructions 3-19 Compute Timestamp Duration (CTSD) A data definitional attribute template (DDAT) template tion of a the in template. The valid values for this first number is a number the data definitional attribute template field are 1, 2, list. and that corresponds to the relative posi- For example the number 1 references 3. The DDAT for operand 1 must be valid for a timestamp duration. The DDATs for operands 2 and 3 must be valid for a timestamp and identical. Otherwise, a emplate value invalid (hex 3801) exception will be signaled. Operand 2 length and The size of the DDAT operand list is 3 length are specified in specified in number of of bytes. bytes. of DDATs is the count of DDATs DDATs that can be specified is 3. The number number specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list to the There should be as many DDAT offsets as there are DDATs specified. The maximum start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the character operands will be defined by the template. For a further description of the data definitional attribute template, see :hdref=DDAT. definitional attributes of the Authorization Required • None. Lock Enforcement 9 None. Exceptions Operands Exception 06 1 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X 15 Data boundary overflow X X 16 Data format X X 17 Data value X X 18 Date boundary underflow X X X X X X X X X X X X Addressing 01 08 10 Space addressing Parameter reference violation Computation Damage Encountered 04 System object 44 20 violation Argument/Parameter 01 OC Other Partial damage state system object damage Machine Support Chapter 3. Date/Time/Timestamp Instructions 3-20 Compute Timestamp Duration (CTSD) Operands Exception 02 Machine check 1 2 3 4 03 Function check 22 X Object Access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 32 36 User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 Other X Space Extension/Truncation X Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-21 Convert Date (CVTD) Convert Date (CVTD) Op Code Operand (Hex) 040F Operand 2 Source date 1 Result date Operand 3 Instruction template Operand 1 Operand 2: Character scalar. Operand 3: Space Character variable scalar. pointer. ILE access CVTD ( var result_date var source_date instnjction_template : : : aggregate; aggregate; space pointer ) Description: The date specified in operand 2 is converted to another calendar external or internal in operand 1. Operand 3 defines the data definitional attributes for operands presentation and placed and 2. The following describes the instruction template. • Instruction template Char(*) — Bin(4) Instruction template size — Operand — Operand — number UBin(2) template number UBin(2) data definitional attribute template 2 data definitional attribute Reserved (binary — Operand — Operand A 1 Char(2) 0) length UBin(2) 2 length UBin(2) 1 — Reserved (binary — Preferred/Found date format UBin(2) — Preferred/Found date separator Char(1) — Reserved (binary Char(23) — Data definitional attribute template Char(2) 0) 0) Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) UBin(4) list UBin(2) Char(10) 0) offset (repeated) UBin(4) data definitional attribute template template Char(*) list - of in 1 number is a the data definitional attribute template template. The valid values for this field are 1 and number list . Char(*) that corresponds to the relative position of a For example the number 1 references the first 2. Chapter 3. Date/Time/Timestamp Instructions 3-22 Convert Date (CVTD) The DDATs operands for 3801) exception Operand If 1 will 1 and 2 must be valid be signaled. length and operand 2 length are specified numbers the data definitional attribute template dation is for a date. performed. The validation will check for in Otherwise, a template value invalid (hex number of bytes. operands 1 and 2 are the same, only data format and data value correctness. for vali- A format of unknown date, time, or timestamp will indicate that operand 2 will be scanned for a valid list of formats that can be scanned, see “Data Definitional Attribute Template” on page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be format. For a specified to select an additional non-scannable format. This preferred format and preferred separator be used first to find a matching format before scanning operand 2. When the preferred format and will preferred separator have a hex value of zero, only the scan occurs. When a format of unknown The size of the DDAT list is timestamp is specified, the preferred/found format and be set to the format and separator found. date, time, or preferred/found separator fields will specified in of DDATs is the count of DDATs DDATs that can be specified is 2. The number number of bytes. specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list to the There should be as many DDAT offsets as there are DDATs specified. The maximum start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the definitional attributes of the operands. The length of the character operands will be defined by the templates. For a further description of the data definitional attribute template, see “Data Definitional bute Template” on page Attri- 3-5. Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 3 Space addressing X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X Other X X X 15 Data boundary overflow X X 16 Data format X violation Argument/Parameter 01 OC 2 Addressing 01 08 1 Parameter reference violation Computation Chapter 3. Date/Time/Timestamp Instructions 3-23 Convert Date (CVTD) Operands Exception 10 1 X X X X X X X X X X Damage Encountered Partial system object damage Machine Support 02 Machine check X 03 Function check X Object Access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X X X X X X X 01 24 Pointer Specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource Control Limit 01 32 36 User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 Other 18 Date boundary underflow 44 22 3 X 04 System object damage state 20 2 17 Data value Space Extension/Truncation X Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-24 Convert Time (CVTT) Convert Time (CVTT) Op Code Operand (Hex) Operand 1 041 F Operand 2 3 Instruction tem- Source time Result time plate Operand /: Character variable scalar. Operand 2: Character scalar. Operand 3: Space pointer. ILE access CVTT ( var result_time var source_time instruction_template : : : aggregate aggregate space pointer ) The time and placed in operand Description: converted to another external or internal presentation Operand 3 defines the data definitional attributes for operands 1 and 2. specified 1. The following describes the • in operand 2 is instruction template. Instruction template Char(*) — Bin(4) Instruction template size - Operand 1 data definitional attribute template number - Operand 2 data definitional — Reserved {binary 0) — Operand — Operand UBin(2) number attribute template UBin(2) Char(2) length UBin(2) 2 length UBin(2) 1 — Reserved (binary — Preferred/Found time format UBin{2) — Reserved (binary Char(1) — Preferred/Found time separator Char(1) — Reserved (binary Char(22) - Data definitional attribute template Char(2) 0) 0) 0) Char(*) list UBin(4) - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of list UBin(2) Char(10) 0) UBin(4) offset (repeated) Char(*) data definitional attribute template number is a number that corresponds to the relative position of a template in the data definitional attribute template list For example the number 1 references the first template. The valid values for this field are 1 and 2. A . Chapter 3. Date/Time/Timestamp Instructions 3-25 Convert Time (CVTT) The DDATs for operands 1 and 2 must be Otherwise, a template value invalid (hex valid for a time. 3801) exception will be signaled. Operand If length and operand 2 length are specified the data definitional attribute template dation A 1 performed. The validation is numbers check will for in number of bytes. operands 1 and 2 are the same, only data format and data value correctness. for vali- format of unknown date, time, or timestamp will indicate that operand 2 will be scanned for a valid list of formats that can be scanned, see “Data Definitional Attribute Template" on format. For a page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be specified to select an additional non-scannable format. This preferred format and preferred separator will be used first to find a matching format before scanning operand 2. When the preferred format and preferred separator have a hex value of zero, only the scan occurs. When a format of unknown date, time, or preferred/found separator fields The size of the DDAT list is will specified in The number number of The DDAT timestamp offset is the number specified, the preferred/found format specified for this instruction template. of bytes from the start of the DDAT and bytes. of DDATs is the count of DDATs DDATs that can be specified is 2. There should be as many is be set to the format and separator found. offsets as there are DDATs DDAT list The maximum to the start of the specific DDAT. specified. A data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the character operands will be defined by the templates. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5. definitional attributes of the Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 3 Space addressing X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X Other X X X violation Argument/Parameter 01 OC 2 Addressing 01 08 1 Parameter reference violation Computation 16 Data format X 17 Data value X Chapter 3. Date/Time/Timestamp Instructions 3-26 Convert Time (CVTT) Operands Exception Damage Encountered 10 04 System object 44 20 22 state system object damage X X X X X X X X Object Access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X X X X X X X Pointer Specification Pointer does not exist Resource Control Limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 X 03 Function check 01 User Profile storage limit 36 Other X 02 Pointer type invalid 32 3 02 Machine check 01 2E 2 Machine Support 01 24 Partial damage 1 X Space Extension/Truncation Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-27 Convert Timestamp (CVTTS) Convert Timestamp (CVTTS) Op Code Operand (Hex) 043 F Operand 1: Operand 2: Character scalar. Operand 3: Space — Operand 2 Input timestamp 1 Converted timestamp Operand 3 Instruction template Character variable scalar. pointer. ILE access CVTTS ( var result_timestamp : var source_timestamp : instruction_template : aggregate aggregate space pointer ) The timestamp specified in operand 2 is converted to another external or internal presenand placed in operand 1. Operand 3 defines the data definitional attributes for operands 1 and 2. Description: tation The following describes the 9 instruction template. Instruction template - Char(*) Instruction template size - Operand - Operand 1 Bin(4) data definitional attribute template 2 data definitional attribute - Reserved (binary - Operand 1 length - Operand 2 length - Reserved (binary number UBin(2) template number UBin(2) Char(2) 0) UBin(2) UBin(2) Char(2) 0) - Preferred/Found timestamp format UBin(2) - Preferred/Found date separator Char(1) - Preferred/Found time separator Char(1) - Reserved (binary 0) - Data definitional attribute Char(22) template list Char(*) - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of list UBin(4) UBin(2) Char(10) 0) offset (repeated) UBin(4) Char(*) A data definitional attribute template number is a number that corresponds to the relative position of a in the data definitional attribute template list For example the number 1 references the first template. The valid values for this field are 1 and 2. template . Chapter 3. Date/Time/Timestamp Instructions 3-28 Convert Timestamp (CVTTS) The DDATs for operands (hex 3801) exception Operand If 1 will 1 and 2 must be valid be issued. length and operand 2 length are specified the data definitional attribute template dation performed. The validation is for a A format of A format of unknown date, time, or will timestamp. Otherwise, a template value invalid in number of bytes. are the same, only data vali- numbers for check format and data value correctness. timestamp for operands 1 and 2 will indicate that timestamp will indicate that operand 2 will be scanned for a valid format. For a list of formats that can be scanned, see “Data Definitional Attribute Template” on page 3-5. With an unknown format, the preferred/found format and preferred/found separator can be specified to select an additional non-scannable format. This preferred format and preferred separator will be used first to find a matching format before scanning operand 2. When the preferred format and preferred separator have a hex value of zero, only the scan occurs. When unknown a format of date, time, or unknown date, time, or preferred/found separator fields The size of the of list is timestamp is specified, the preferred/found format and be set to the format and separator found. specified in bytes. DDATs is the count of DDATs DDATs that can be specified is 2. The number number DDAT will of specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list There should be as many DDAT offsets as there are DDATs specified. The maximum to the start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the character operands will be defined by the templates. For a further description of the data definitional attribute template, see “Data Definitional Attri- definitional attributes of the bute Template” on page 3-5. Authorization Required • None. Lock Enforcement - None. Exceptions Operands 1 2 3 X X X 02 Boundary alignment X X X 03 Range X X X 06 Optimized addressability invalid X X X X X X Exception 06 Addressing 01 08 Space addressing violation Argument/Parameter 01 0C Other Parameter reference violation Computation Chapter 3. Date/Time/Timestamp Instructions 3-29 Convert Timestamp (CVTTS) Operands Exception 15 Data boundary overflow 10 20 22 X 17 Data value X 18 Date X boundary underflow X X X X 44 X X X X Partial system object damage Machine Support 02 Machine check X 03 Function check X Object Access Object not found X X X 02 Object destroyed X X X 03 Object suspended X X X X X X X X X Pointer Specification Pointer does not exist Resource Control Limit 01 36 User Profile storage limit exceeded X Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 Other 04 System object damage state 02 Pointer type invalid 32 3 Damage Encountered 01 2E 2 X 16 Data format 01 24 1 Space Extension/Truncation X Template Specification 01 Template value invalid X Chapter 3. Date/Time/Timestamp Instructions 3-30 Decrement Date (DECD) Decrement Date (DECD) Op Code Operand (Hex) 1 Result date 0414 Operand 1\ Character variable scalar. Operand 2: Character scalar. Operand 3: Packed decimal Operand 4: Space Operand Operand 2 Source date Operand 4 3 Instruction template Duration scalar. pointer. 1LE access i DECD ( var result_date var source_date aggregate ; aggregate ; packed decimal space pointer var duration i nstructi on_templ ate ; ) The date specified by operand 2 is decremented by the date duration specified by The resulting date from the operation is placed in operand 1. Operand 4 defines the data attributes for operands 1 through 3. Description: operand 3. definitional The following describes the a instruction template. Instruction template Char(*) - Bin(4) Instruction template size - Operand — Operand - Operand — Operand — Operand — Operand - 2 data definitional attribute UBin(2) template number UBin(2) number UBin(2) 3 data definitional attribute template 1 length UBin(2) 2 length UBin(2) 3 length UBin(2) - Fractional - Total number number Char(1) of digits Char(1) of digits Char(2) Input indicators - - End of month adjustment 0 = No 1 = 1 - Bit 0 Bit 1 adjustment Adjustment Tolerate data decimal errors 0 — number data definitional attribute template 1 = No toleration = Tolerate Reserved (binary Bit 2-15 0) Char(2) Output indicators Chapter 3. Date/Time/Timestamp Instructions 3-31 Decrement Date (DECD) End of month adjustment - = No 1 = 0 adjustment Adjustment Reserved (binary - A 0 Bit Bit 1-15 0) - Reserved (binary — Data definitional attribute template Char(22) 0) Char(*) list - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of UBin(4) list UBin(2) Char(10) 0) offset (repeated) UBin(4) Char(*) data definitional attribute template (DDAT) number is a number that corresponds to the relative positemplate in the data definitional attribute template list For example the number 1 references tion of a the first . template. The valid values for this The DDATs be valid for for a Operand 1 operands 1 and date duration. 2 must be are field valid for a date of 3. and identical. The DDAT for Otherwise, a template value invalid (hex 3801) exception length and operand 2 length are specified in The input indicator, end month adjustment. and 1, 2, month adjustment , number operand 3 must will be issued. of bytes. used to allow or disallow the occurrence of an end of is The input indicator, tolerate decimal data errors is used packed data for the duration will generate exceptions or , to determine will whether errors found be ignored. When in the the errors are to be tolerated, the following rules will apply: 1. An 2. Any 3. invalid sign nibble found in the invalid decimal digits found in packed data value will be changed to a hex F. the packed data value will be forced to zero. digits of a packed data value become zero, and no decimal overflow condition exists, the sign be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will not be changed, but its representation will be changed to the preferred sign code. If all will The output indicator, end of month adjustment end of month adjustments are allowed. , is used to indicate an end of month adjustment, when End of month adjustment is the following concept. For SAA, the result of subtracting a 1 month durafrom the Gregorian date 03/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 is changed to 28. When this happens, the end of month adjustment output indicator is set to on. tion When end month adjustments are not allowed, the month and year definitions in the data definition must have values greater than zero, otherwise a template value invalid (hex 3801) exception will be signalled. The result of subtracting a 1 month duration from the Gregorian date 03/31/1989 is 03/01/1989, when the definition of a month is 30 days. of attribute template The size of the of list is specified in bytes. of DDATs is the count of DDATs DDATs that can be specified is 3. The number number DDAT specified for this instruction template. Chapter 3. The maximum Date/Time/Timestamp Instructions 3-32 Decrement Date (DECD) the The DDAT offset is the number of bytes from the start of DDATs There should be as many DDAT offsets as there are DDAT to the start of the specific list DDAT. specified. presentation of the data. Each template describes data definitional attribute template defines the operands of the date and date duration character definitional attributes of the operands. The length see of the data definitional attribute template, be defined by the template. For a further description A “Data Definitional Attribute Template” on page will 3-5. Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 Space addressing violation 02 Boundary alignment Range 03 04 06 Optimized addressability invalid 3 4 X X X X X X X X X X X X X X X X X X X X Argument/Parameter 01 0C 2 Addressing 01 08 Parameter reference violation Computation X 02 Decimal data X X 15 Date boundary overflow X 16 Data format X 17 Data value 18 Date boundary underflow 10 X X X X X X X X X X X X Damage Encountered System object damage state 44 20 Other 1 Partial system object damage Machine Support X 02 Machine check X 03 Function check 22 Object Access 01 Object not found 02 Object destroyed 03 Object suspended 24 X X X X X X X X X X X X X X X X X X X X Pointer Specification 01 Pointer does not exist 02 Pointer type invalid Chapter 3. Date/Time/Timestamp Instructions 3-33 Decrement Date (DECD) Operands “12 Exception 2E Resource Control Limit 01 User Profile storage limit 32 Other X Scalar Specification 02 Scalar attributes invalid X X X X Space Management 01 38 4 exceeded 03 Scalar value invalid 36 3 Space Extension/Truncation X Template Specification 01 Template value invalid X Chapter 3. Date/Time/Timestamp Instructions 3-34 Decrement Time (DECT) Decrement Time (DECT) Op Code Operand (Hex) 1 Result time 0444 Operand 1: Character variable scalar. Operand 2: Character scalar. Operand 3: Packed decimal Operand 4\ Space — Operand Operand 2 Operand 4 3 Instruction template Duration Source time scalar. pointer. iLt access DECT ( var result_time var source_time aggregate ; aggregate ; packed decimal space pointer : : var duration instruction_temp1ate : : ; ) The time specified by operand 2 is decremented by the time duration specified by data operand 3. The resulting time from the operation is placed in operand 1. Operand 4 defines the definitional attributes for operands 1 through 3. Description: The following describes the « instruction template. Instruction template CharO - Bin(4) Instruction template size - Operand - Operand 1 data definitional attribute template number UBin(2) 2 data definitional attribute template number UBin(2) template number UBin(2) - Operand 3 data definitional attribute - Operand 1 length UBin(2) - Operand 2 length UBin(2) - Operand 3 length UBin(2) - - Fractional - Total number number Char(1) of digits Char(1) of digits Char(2) Input indicators - Reserved (binary - Tolerate data decimal errors 0 1 - Bit 1 = No toleration = Tolerate Reserved (binary Reserved (binary - Data definitional attribute template Size of the Bit 2-15 0) - - Bit 0 0) Char(24) 0) DDAT Char(*) list UBin(4) list Chapter 3. Date/Time/Timestamp Instructions 3-35 Decrement Time (DECT) - Number - Reserved (binary - DDAT — d , the DDATs UBin(2) 0) Char(10) offset (repeated) UBin(4) Data definitional attribute template (repeated) - A of f miti ° nal attribute template (DDAT) number the <* efinitiona ! The DDATs be valid Operand 1 operands for for a 1 a are field 1, 2, lengt h and o perand 2 length are specified in Any 3. invalid sign nibble found in the decimal invalid that corresponds to the relative posi- For example the number 1 references 3. number tolerated, the following rules will apply: 2. and . 2 must be valid for a time and identical. The DDAT for operand 3 must Otherwise, a template value invalid (hex 3801) exception will be issued. , An list and time duration. The in put indicator, tolerate decimal d ata errors is used packed data for the duration will generate exceptions or 1. number attribute template l" ^ template. The valid values for this first is Charf) digits found in packed data value to of bytes. determine whether errors found in the be ignored. When the errors are to be will will the packed data value be changed to a hex will F. be forced to zero. packed data value become zero, and no decimal overflow condition exists, the sign wi be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will not be changed, but its representation will be changed to the If digits of a all preferred sign code. The size of the DDAT list is specified The number number of in bytes. of DDATs is the count of DDATs DDATs that can be specified is 3. specified for this instruction template. The D DAT offset is the number of bytes from the start of the DDAT list There should be as many DDAT offsets as there are DDATs specified. The maximum to the start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes the The length of the time and time duration character operands will be defined by the templates. For a further description of the data definitional attribute template see Data Definitional Attribute Template” on page 3-5. definitional attributes of the operands. Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 2 3 4 X X X X X X X X X X X X 1 06 Other Addressing 01 Space addressing violation 02 Boundary alignment 03 Range Chapter 3. Date/Time/Timestamp Instructions 3-36 Decrement Time (DECT) Operands Exception 06 Optimized addressability invalid 08 2 3 4 X X X X X X X Argument/Parameter 01 OC Parameter reference violation Computation X 02 Decimal data 10 16 Data format X 17 Data value X Damage Encountered 04 System object 44 20 22 Partial damage state system object damage X X X X X X X Object Access X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X Object not found Pointer Specification Pointer does not exist Resource Control Limit User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 X 03 Function check 01 36 X X 02 Pointer type invalid 32 X 02 Machine check 01 2E X Machine Support 01 24 Other 1 X X Space Extension/Truncation Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-37 Decrement Timestamp (DECTS) Decrement Timestamp (DECTS) Op Code (Hex) 0420 Operand 1 Res ult timestamp Operand 1: Operand 2: Character scalar. Operand 3: Packed decimal Operand 4: Space Operand 2 Source timestamp Operand Operand 4 3 Duration Instruction template Character variable scalar. scalar. pointer. DECTS ( var result_timestamp var source_timestamp var duration : : : instruction_temp1ate : aggregate ; aggregate ; packed decimal space pointer ; ) Description: The timestamp specified by operand 2 is decremented by the date, time, or timestamp duration specified by operand 3. The resulting timestamp from the operation is placed in operand 1. Operand 4 defines the data definitional attributes for operands The following describes the • 1 through instruction template. Instruction template Char(*) - Instruction template size - Operand - Operand - Operand 1 2 data definitional attribute UBin(2) template number UBin(2) data definitional attribute template 1 length - Operand 3 length - Fractional - Total UBin(2) UBin(2) UBin(2) UBin(2) number number number of digits Char(1) of digits Char(1) Input indicators - 1 - 1 Bit 0 Bit 1 = No adjustment = Adjustment Tolerate data decimal errors 0 - Char(2) End of month adjustment 0 - number 3 2 length — Bin(4) data definitional attribute template - Operand - Operand 3. = No toleration = Tolerate Reserved (binary 0) Bit 2-15 Output indicators Char(2) Chapter 3. Date/Time/Timestamp Instructions 3-38 Decrement Timestamp (DECTS) Bit End of month adjustment - 0 = No 1 = adjustment Adjustment Reserved (binary - 0 Reserved (binary Bit 1-15 0) Char(22) 0) Data definitional attribute template Char(‘) list - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of UBin(4) list UBin(2) Char(10) 0) UBin(4) offset (repeated) CharO data definitional attribute template fDDAT) number is a number that corresponds to the relative posireferences tion of a template in the data definitional attribute template list For example the number 1 the first template. The valid values for this field are 1, 2, and 3. A . The DDATs for operands 1 and 2 must be valid for a timestamp and identical. The DDAT for operand 3 must be valid for a timestamp duration. Otherwise, a template value invalid (hex 3801) exception will be issued. Operand 1 length and operand 2 length are specified The input indicator, end month adjustment. of month adjustment number of bytes. used to allow or disallow the occurrence of an end of is , in The input indicator, tolerate decimal data errors is used packed data for the duration will generate exceptions or , whether errors found in the be ignored. When the errors are to be to determine will tolerated, the following rules will apply: 1. An 2. Any 3. invalid sign nibble invalid decimal found digits in the packed data value found in will be changed to a hex F. the packed data value will be forced to zero. packed data value become zero, and no decimal overflow condition exists, the sign the sign will will be set to hex F. If all digits are zero and a decimal overflow condition exists, then code. not be changed, but its representation will be changed to the preferred sign If all digits of a The output indicator, end of month adjustment end of month adjustments are allowed. , is used to indicate an end of month adjustment, when For SAA, the result of subtracting a 1 month durais changed tion from the date 03/31/1989 is 02/28/1989. The days portion is adjusted to fit the month, 31 set to on. indicator is to 28. When this happens, the end of month adjustment output End of month adjustment is the following concept. month adjustments are not allowed, the month and year definitions in the data definition attribute template must have values greater than zero, otherwise a template value invalid (hex 3801) exception will be signaled. The result of subtracting a 1 month duration from the Gregorian date 03/31/1989 is 03/01/1989, when the definition of a month is 30 days. When end The size of of the of list is specified in bytes. DDATs is the count of DDATs DDATs that can be specified is 3. The number number DDAT of specified for this instruction template. Chapter 3. The maximum Date/Time/Timestamp Instructions 3-39 Decrement Timestamp (DECTS) The DDAT offset number of bytes from the start of the DDAT list to be as many DDAT offsets as there are DDATs specified. is the the start of the specific DDAT. There should A data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the timestamp and duration character operands will be defined by the template. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5. definitional attributes of the Authorization Required » None. Lock Enforcement • None. Exceptions Operands Exception 06 01 08 2 3 4 Space addressing violation X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X Parameter reference violation Computation 02 Decimal data X 15 Date boundary overflow X X 17 Data value X boundary underflow X X X X X X X X X X X X Damage Encountered 04 System object 44 20 X 16 Data format 18 Date 10 Partial damage state system object damage Machine Support 02 Machine check X 03 Function check 22 X Object Access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X 01 24 Other Argument/Parameter 01 OC 1 Addressing Pointer Specification 01 Pointer does not exist Chapter 3. Date/Time/Timestamp Instructions 3-40 Decrement Timestamp (DECTS) Operands Exception 02 Pointer type invalid 2E 36 3 4 X X X Other User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 2 Resource Control Limit 01 32 1 X X Space Extension/Truncation Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-41 Increment Date (INCD) Increment Date (INCD) Op Code (Hex) Operand 0404 Operand /: Operand 2: Character scalar. Operand 3\ Packed decimal Operand 4: Space INCD 1 Result date Operand 2 Source date Operand 3 Operand 4 Duration Instruction template Character variable scalar. scalar. pointer. ( var result_date var source_date var duration aggregate ; aggregate-, packed decimal-, space pointer instruction_template ) The date specified by operand 2 is incremented by the date duration specified by The resulting date from the operation is placed in operand 1. Operand 4 defines the data attributes for operands 1 through 3. Description: operand 3. definitional The following describes the instruction template. Instruction template Charf) - Instruction template size - Operand - Operand - Operand 1 2 data definitional attribute UBin{2) template number UBin(2) data definitional attribute template 1 length 2 length - Operand 3 length - Fractional - Total UBin(2) UBin(2) UBin(2) UBin(2) number number number of digits Char(1) of digits Char{1) Input indicators - 1 - 1 Bit 0 Bit 1 = No adjustment = Adjustment Tolerate data decimal errors 0 - Char(2) End of month adjustment 0 — number 3 - Operand - Operand — Bin(4) data definitional attribute template = No toleration = Tolerate Reserved (binary 0) Bit 2-15 Output indicators Char(2) Chapter 3. Date/Time/Timestamp Instructions 3-42 Increment Date (INCD) BitO End of month adjustment - 0 1 = No adjustment = Adjustment Reserved (binary - Reserved (binary Bit 1-15 0) Char(22) 0) Data definitional attribute template A Char(’) list - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of UBin(4) list UBin(2) Char(10) 0) UBin(4) offset (repeated) data definitional attribute template (DDAT) number is Char(*) number a that corresponds to the relative position of a template in the data definitional attribute template list For example the number the first template. The valid values for this field are 1, 2, and 3. . The DDATs be valid for for a Operand operands 1 and date duration. 2 must be valid for a date length and operand 2 length are specified 1 The input indicator, end month adjustment. of and identical. The DDAT for Otherwise, a template value invalid (hex 3801) exception month adjustment is , in number 1 references operand will 3 must be issued. of bytes. used to allow or disallow the occurrence of an end of The input indicator, tolerate decimal data errors is used packed data for the duration will generate exceptions or to determine whether errors found be ignored. will When in the the errors are to be tolerated, the following rules will apply: invalid sign nibble found in the 1. An 2. Any 3. invalid decimal digits found in packed data value will the packed data value be changed to a hex will F. be forced to zero. packed data value become zero, and no decimal overflow condition exists, the sign will will be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign code. sign the preferred not be changed, but its representation will be changed to If all digits of a The output indicator, end of month adjustment end of month adjustments are allowed. , is used to indicate an end of month adjustment, when For SAA, the result of adding a portion is adjusted to fit the month, 31 days The the date 01/31/1989 is indicator is set to on. output adjustment When this happens, the end of month End of month adjustment is the following concept. 02/28/1989. When end of month adjustments are not allowed, the month and year 1 is month duration changed to 28. to definitions in the data definition attribute template must have values greater than zero, otherwise a template value invalid (hex 3801) exception will be signaled. The result of adding a 1 month duration to the Gregorian date 01/31/1989 03/02/1989, The size when of the of DDAT list is month specified in is bytes. of DDATs is the count of DDATs DDATs that can be specified is 3. The number number the definition of a is 30 days. specified for this instruction template. Chapter 3. The maximum Date/Time/Timestamp Instructions 3-43 Increment Date (INCD) The DDAT offset is the number of bytes from the start of the DDAT list to the There should be as many DDAT offsets as there are DDATs specified. start of the specific DDAT. A data definitional attribute template defines the presentation of the data. Each template describes operands. The length of the date and date duration character operands be defined by the template. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5. definitional attributes of the will Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 01 08 2 3 4 Space addressing violation X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X Parameter reference violation Computation 02 Decimal data X 15 Date boundary overflow X 16 Data format X 18 Date boundary underflow X X X X X X X X X X X X Damage Encountered 04 System object 44 20 X X 17 Data value 10 Partial damage state system object damage Machine Support 02 Machine check X 03 Function check 22 X Object Access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 24 Other Argument/Parameter 01 OC 1 Addressing Pointer Specification 01 Pointer does not exist 02 Pointer type invalid Chapter 3. Date/Time/Timestamp Instructions 3-44 Increment Date (INCD) Operands Exception 2E 01 32 36 2 3 4 Other User Profile storage limit X exceeded Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 1 Resource Control Limit X Space Extension/Truncation Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-45 Increment Time (INCT) Increment Time (INCT) Op Code (Hex) Operand 0434 Operand 1: Operand 2: Character scalar. Operand 3: Packed decimal Operand 4: Space INCT Operand 2 Source time 1 Result time Operand 3 Operand 4 Duration Instruction template Character variable scalar. scalar. pointer. ( var result_time var source_time var duration aggregate ; aggregate ; packed decimal space pointer instruction_temp1ate ; ) The time specified by operand 2 is incremented by the time duration specified by The resulting time from the operation is placed in operand 1. Operand 4 defines the data attributes for operands 1 through 3. Description: operand 3. definitional The following describes the 3 instruction template. Instruction template Char(*) - Instruction template size - Operand - Operand - Operand 1 Bin(4) data definitional attribute template 2 data definitional attribute number UBin{2) template number UBin(2) 3 data definitional attribute template 1 number UBin(2) - Operand - Operand length UBin(2) 2 length UBin(2) - Operand 3 length UBin(2) - - Fractional - Total number number of digits Char(1) of digits Char(1) Input indicators Char(2) - Reserved (binary - Tolerate data decimal errors 0 1 - 0) 0 Bit 1 = No toleration = Tolerate Reserved (binary 0) — Reserved (binary - Data definitional attribute template - Bit Size of the Bit 2-15 0) DDAT Char(24) list Char(*) list UBin{4) Chapter 3. Date/Time/Timestamp Instructions 3-46 increment Time (1NCT) A DDATs - Number - Reserved (binary - DDAT - Data definitional attribute template (repeated) of UBin(2) Char(10) 0) data definitional attribute template template tion of a the first in number (DDAT) for operands 1 Operand 1 field are 1, 2, list and . corresponds to the relative posi- that For example the number 1 references 3. 2 must be valid for a time and identical. The DDAT for operand 3 must Otherwise, a template value invalid (hex 3801) exception will be issued. leng th and operand 2 length are specified for the duration will in number of bytes. is used to determine whether errors found in the generate exceptions or will be ignored. When the errors are to be input indicator, tolerate decimal data errors packed data number a and for a time duration. be valid is Char(*) the data definitional attribute template template. The valid values for this The DDATs The UBin(4) offset (repeated) , tolerated, the following rules will apply: 1. An 2. Any 3. If invalid sign nibble found in the invalid decimal digits found digits of a all packed data value will the packed data value in be changed to a hex will F. be forced to zero. packed data value become zero, and no decimal overflow condition exists, the sign If all digits are zero and a decimal overflow condition exists, then the sign will its representation will be changed to the preferred sign code. be set to hex F. not be changed, but will The size of the of list is specified in bytes. DDATs is the count of DDATs DDATs that can be specified is 3. The number number DDAT of specified for this instruction template. The DDAT offset is the number of bytes from the start of the DDAT list to the There should be as many DDAT offsets as there are DDATs specified. The maximum start of the specific DDAT. data definitional attribute template defines the presentation of the data. Each template describes the definitional attributes of the operands. The length of the time and time duration character operands will A be defined by the templates. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5. Authorization Required • None. Lode Enforcement • None. Exceptions Operands 1 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X Exception 06 Other Addressing 01 Space addressing violation Chapter 3. Date/Time/Timestamp Instructions 3-47 Increment Time (INCT) Operands Exception 06 Optimized addressability invalid 08 2 3 4 X X X X X X X Parameter reference violation Computation 02 Decimal data 10 X 16 Data format X 17 Data value X Damage Encountered 04 System object damage state 44 20 22 Partial system object damage X X X X X X X Object Access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X Pointer Specification Pointer does not exist Resource Control Limit User Profile storage limit exceeded X Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 X X 01 36 X 03 Function check 02 Pointer type invalid 32 X 02 Machine check 01 2E X Machine Support 01 24 Other Argument/Parameter 01 OC 1 X Space Extension/Truncation X Template Specification 01 Template value X invalid Chapter 3. Date/Time/Timestamp Instructions 3-48 Increment Timestamp (INCTS) Increment Timestamp (INCTS) Op Code Operand 1 Result timestamp (Hex) 040C Operand 1: Character variable scalar. Operand 2: Character scalar. Operand 3: Packed decimal Operand 4: Space INCTS Operand 4 Duration Instruction template pointer. — ( var result_timestamp var source_timestamp j Operand 3 scalar. ILE access I | Operand 2 Source timestamp aggregate ; : aggregate-, : j var duration instruction_template | packed decimal-, space pointer : : | I ) The timestamp specified by operand 2 is incremented by the date, time, or timestamp 3. The resulting timestamp from the operation is placed in operand 1. Operand 4 defines the data definitional attributes for operands 1 through 3. Description: duration specified by operand The following describes the • instruction template. Instruction template Char(*) - Bin(4) Instruction template size - Operand - Operand — Operand number UBin(2) template number UBin(2) number UBin(2) data definitional attribute template 1 2 data definitional attribute 3 data definitional attribute template - Operand 1 length UBin(2) - Operand 2 length UBin(2) — Operand 3 length UBin(2) — - Fractional - Total number Char(1) of digits Char(1) of digits Char(2) Input indicators - - 0 = No 1 = adjustment Adjustment Bit Tolerate data decimal errors 1 - Bit 0 End of month adjustment 0 - number 1 = No toleration = Tolerate Reserved (binary Bit 2-15 0) Char(2) Output indicators Chapter 3. Date/Time/Timestamp Instructions 3-49 increment Timestamp (INCTS) End of month adjustment - 0 1 - Reserved — A = No adjustment = Adjustment Reserved (binary - Bit 0 Bit 1-15 0) (binary 0) Char(22) Data definitional attribute template - Size of the DDAT - Number DDATs - Reserved (binary - DDAT - Data definitional attribute template (repeated) of UBin(4) list UBin(2) Char(10) 0) offset (repeated) UBin(4) data definitional attribute template (DDAT) template tion of a the first Char(*) list in number is Char(*) number a the data definitional attribute template template. The valid values for this are field list and 1, 2, . that corresponds to the relative posi- For example the number 1 references 3. The DDATs for operands 1 and 2 must be valid for a timestamp and identical. The DDAT for operand 3 must be valid for a timestamp duration. Otherwise, a template value invalid (hex 3801) exception will be issued. Operand 1 length and operand 2 length are specified The input indicator, end month adjustment. of month adjustment , in number of bytes. used to allow or disallow the occurrence of an end of is The input indicator, tolerate decimal data errors is used packed data for the duration will generate exceptions or , to determine whether errors found in the be ignored. When the errors are to be will tolerated, the following rules will apply: 1. An 2. Any 3. invalid sign nibble found in the invalid decimal digits found in packed data value will the packed data value be changed to a hex will F. be forced to zero. digits of a packed data value become zero, and no decimal overflow condition exists, the sign be set to hex F. If all digits are zero and a decimal overflow condition exists, then the sign will not be changed, but its representation will be changed to the preferred sign code. If all will The output indicator, end of month adjustment end of month adjustments are allowed. End of month adjustment the date 01/31/1989 When this When end is is , is used the following concept. 02/28/1989. The days portion to indicate an end of month adjustment, when For SAA, the result of adding a is adjusted to fit the month, 31 happens, the end of month adjustment output indicator is 1 is month duration changed to 28. to set to on. month adjustments are not allowed, the month and year definitions in the data definition must have values greater than zero, otherwise a template value invalid (hex 3801) exception will be signaled. The result of adding a 1 month duration to the Gregorian date 01/31/1989 03/02/1989, when the definition of a month is 30 days. of attribute template The size of the of iist is specified in bytes. of DDATs is the count of DDATs DDATs that can be specified is 3, The number number DDAT is specified for this instruction template. Chapter 3. The maximum Date/Time/Timestamp Instructions 3-50 Increment Timestamp (INCTS) The DDAT offset is the number of bytes from the start of the DDAT list There should be as many DDAT offsets as there are DDATs specified. A to the start of the specific DDAT. data definitional attribute template defines the presentation of the data. Each template describes the operands. The length of the timestamp and duration character operands be defined by the template. For a further description of the data definitional attribute template, see “Data Definitional Attribute Template” on page 3-5, definitional attributes of the will Authorization Required • None. Lock Enforcement • None. Exceptions Operands Exception 06 1 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X Addressing 01 08 Space addressing violation Argument/Parameter 01 0C Parameter reference violation Computation X 02 Decimal data X 15 Date boundary overflow X 17 Data value X 44 22 X X X X X X Partial system object damage X X X X X Machine Support 02 Machine check X 03 Function check X Object Access X X X X 02 Object destroyed X X X X 03 Object suspended X X X X X X X X X X X X 01 24 X Damage Encountered 04 System object damage state 20 X 16 Data format 18 Date boundary underflow 10 Other Object not found Pointer Specification 01 Pointer does not exist 02 Pointer type invalid Chapter 3. Date/Time/Timestamp Instructions 3-51 Increment Timestamp (INCTS) Operands Exception 2E Resource Control Limit 01 32 36 Profile storage limit 2 3 4 exceeded Other X Scalar Specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space Management 01 38 User 1 Space Extension/Truncation X Template Specification 01 Template value X invalid Chapter 3, Date/Time/Timestamp Instructions 3-52 Pointer/Name Resolution Addressing Instructions Chapter 4. Pointer/Name Resolution Addressing Instructions This chapter describes the instructions used for pointer and name resolution functions. These instructions are in alphabetic order. See Appendix A, “Instruction Summary," for an alphabetic summary of all the instructions. Compare Pointer for Object Addressability (CMPPTRA) Compare Pointer for Space Addressability (CMPPSPAD) Compare Pointers for Equality (CMPPTRE) Compare Pointer Type (CMPPTRT) Copy Bytes with Pointers (CPYBWP) 4-3 4-5 4-7 4-9 4-12 Resolve Data Pointer (RSLVDP) Resolve System Pointer (RSLVSP) 4_14 Set Space Pointer from Pointer (SETSPPFP) Set System Pointer from Pointer (SETSPFP) 4-22 © Copyright IBM Corp. 1991, 1993 4-17 4-24 4-1 Pointer/Name Resolution Addressing Instructions Chapter 4. Pointer/Name Resolution Addressing Instructions 4-2 Compare Compare Op Code Pointer for Object Addressability (CMPPTRA) Pointer for Object Addressability Operand Extender Branch options (Hex) CMPPTRAB operand CMPPTRAI Operand 1 Compare 1CD2 operand Operand 2 Compare Compare operand 1 Indicator targets 2 Operand 1: Data pointer, space pointer, system pointer, or instruction pointer. Operand 2: Data pointer, space pointer, system pointer, or instruction pointer. Operand 3 3 [4] Branch targets operand 2 1 Compare Indicator options 18D2 (CMPPTRA) [4]: • Branch Form — Instruction number, • Form - Numeric Indicator relative instruction number, branch point, or instruction pointer. variable scalar or character variable scalar. The object addressed by operand 1 is compared with the object addressed by operand 2 both operands are addressing the same object. Based on the comparison, the resulting condition is used with the extender to transfer control (branch form) or to assign a value to each of the indicator operands (indicator form). Description: to determine if If operand 1 is a data pointer, a space pointer, or a system pointer, operand 2 may be any pointer type except for instruction pointer in any combination. An equal condition occurs if the pointers are addressing the same object. For space pointers and data pointers, only the space they are addressing is considered in the comparison. That is, the space offset portion of the pointer For system pointer compare operands, an equal condition occurs if with a space pointer or data pointer that addresses the space that is ignored. the system pointer is is compared associated with the object that is addressed by the system pointer. For example, a space pointer that addresses a byte in a space associated with a system object compares equal with a system pointer that addresses the system object. For instruction pointer comparisons, both operands must be instruction pointers; otherwise, an invalid is signaled. An equal condition occurs when both instruction pointers are addressing the same instruction in the same program. A not equal condition occurs if the instruc- pointer type (hex 2402) exception tion pointers are not addressing the A same instruction in the pointer does not exist (hex 2401) exception operands. is signaled if same program. a pointer does not exist in either of the Resultant Conditions • Equal • Not equal Authorization Required • Retrieve — Contexts referenced for address resolution Lode Enforcement 9 Materialize — Contexts referenced for address resolution Chapter 4. Pointer/Name Resolution Addressing Instructions 4-3 Compare Pointer for Object Addressability (CMPPTRA) Exceptions 06 Operands 3 4 X X X X X X X X X X X X X X X X X X X X X X X X 1 2 X 02 Boundary alignment X 01 Range 03 06 Optimized addressability invalid Exception Other Addressing 01 01 08 Space addressing violation Argument/parameter Parameter reference violation 0A Authorization Unauthorized 10 for operation Damage encountered 04 System object damage state 05 authority verification terminated due to 44 1A X object system object damage X X X X X X Invalid lock state Machine-dependent exception X 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X Object access X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 01 24 Object not found 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X X X limit 01 user profile storage limit 36 X Lock state 01 1C Partial damaged X X exceeded Space management 01 X space extension/truncation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-4 Compare Compare Op Code Pointer for Space Addressability Operand Extender Branch options (Hex) CMPPSPADB Operand CMPPSPADI Operand 1: Operand 2: Space pointer or data Numeric variable Operand 1 Operand 3 2 Compare 1 Operand 1 Operand Compare Indicator options 18E6 (CMPPSPAD) (CMPPSPAD) Compare 1CE6 Operand Pointer for Space Addressability [4-6] Branch targets 2 Compare Indicator targets 2 pointer. scalar, character variable scalar, numeric variable array, character variable array, space pointer, or data pointer. Operand 3 [4-6]: • Branch Form-Instruction number, • Indicator relative instruction Form-Numeric variable scalar or character variable The space addressability contained in with the space addressability defined by operand 2. Description: The value of the operand • If is 9 If number, branch operand 2 compared operand contained is 1 pointer is compared based on the a pointer, is the pointer it is in 1 is compared following: a scalar data object (element or array), the 2 scalar. the pointer specified by operand with the space addressability contained in point, or instruction pointer. space addressability of that data object the operand 1 pointer. must be a space pointer or data pointer, and the space addressability compared with the space addressability contained in the operand 1 pointer. Based on the results of the comparison, the resulting condition is control (branch form) or to assign a value to each of the indicator used with the extender to transfer operands (indicator form). If the operands are not in the same space, the resultant condition is unequal. If the operands are in the same space and the offset into the space of operand 1 is larger or smaller than the offset of operand 2, the resultant condition is high or low, respectively. An equal condition occurs only if the operands are in the same space at the same offset. Therefore, the resultant conditions {high, low, equal and unequal) are mutually exclusive. Consequently, if you specify that an action be taken upon the nonexistence of a condition, this results in the action being taken upon the occurrence of any of the other three possible conditions. For example, a branch not high would result in the branch being taken on a low, equal, or unequal condition. , The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are not signaled when operand 1 or operand 2 is a space pointer machine object or when operand 2 is a scalar based on a space pointer machine object. This occurs when the space pointer machine object contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, the resulting condition of the comparison operation is not defined other than that it will be one of the four valid resultant conditions for this instruction. When the Override Program Attributes (OVRPGATR) instruction is used to override this instruction, the pointer does not exist (hex 2401) exception is not signaled when operand 1 or operand 2 is a space pointer (i.e. either a space pointer data object or a space pointer machine object). Furthermore, some , comparisons involving space pointers are defined even when one or both of the compare operands a pointer subject to the pointer does not exist condition. Specifically, if both compare operands are subject to the pointer does not exist condition, the resultant condition is equal. When one space pointer is set and one is subject to the pointer does not exist condition, the resultant condition is Chapter 4. Pointer/Name Resolution Addressing Instructions is 4-5 Compare Pointer for Space Addressability (CMPPSPAD) unequal, but undefined with respect to comparisons which include specification of the high or low conditions. Resultant Conditions • High • Low • Equal • Unequal Exceptions Operands Exception 06 08 1 2 01 space addressing violation X X 02 boundary alignment X X 03 range X X 04 external data object not found X X 06 optimized addressability invalid X X X X Argument/parameter parameter reference violation Damage encountered damage 04 system object 44 1C Other Addressing 01 10 3 [4-6] partial state system object damage X X X X X X X X Machine-dependent exception 03 machine storage limit exceeded 20 22 X Machine support 02 machine check X 03 function check X Object access XXX XXX XXX XXX XXX 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 36 exceeded X Space management 01 space extension/truncation X Chapter 4. Pointer/Name Resolution Addressing Instructions 4-6 Compare Compare 1 Operand Extender Branch options Operand 1 operand operand [4] Branch targets operand 2 1 Compare Indicator options 1812 Operand 3 2 Compare Compare Cl 2 CMPPTREI (CMPPTRE) (CMPPTRE) Pointers for Equality Op Code (Hex) CMPPTREB Pointers for Equality Compare Indicator targets operand 2 1 Operand 1: Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, procedure pointer, label pointer, or suspend pointer Operand 2: Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, procedure pointer, label pointer, or suspend pointer Operand 3 [4]: • Branch Form -Instruction number, » Indicator Form — Numeric relative instruction number, branch point, or instruction pointer. variable scalar or character variable scalar. The pointer specified by operand 1 is compared with the pointer specified by operand 2 determine if both operands are of the same type and contain equal values. Based on the compar- Description: to ison, the resulting condition is used with the extender to transfer control (branch form) or to assign a value to each of the indicator operands (indicator form). may be any combination. An equal condition occurs if the pointers are of the same type and contain the same value, or if neither pointer has been set. If one pointer is set and the other is not, a not equal condition occurs. Pointers specified for operands 1 and 2 in System pointers and data pointers are not resolved by this instruction. The comparison fined when an unresolved pointer is supplied for one or both operands. Note that any authorities stored pointers pointing to the same in result is unde- a resolved system pointer are part of the pointer. Thus system object, but with different levels of authority, will compare as not equal. Since any pointer type may be specified for this instruction, the invalid pointer type (hex 2402) excepis not signaled except for pointers used as a base for the operands. Similarly, since the instruction tion accepts unset pointers, the pointer does not exist (hex 2401) exception is not signaled except for pointers used as a base for the operands. Resultant Conditions • Equal • Not equal Exceptions Operands 1 2 3 4 X X X X 02 Boundary alignment X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X Exception 06 Other Addressing 01 Space addressing violation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-7 Compare Pointers for Equality (CMPPTRE) Operands 1 Exception I 08 01 0A Parameter reference violation Unauthorized for operation damage state 05 authority verification terminated due to 44 4 X X X X X X X X X X X X X X X X Partial damaged system object damage 22 Invalid lock state X Machine support 02 Machine check X 03 Function check X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X X X limit 01 user profile storage limit 36 X Machine-dependent exception 01 24 X X object 03 Machine storage limit exceeded 20 Other Lock state 01 1C 3 Damage encountered 04 System object 1 2 Authorization 01 10 1 Argument/parameter exceeded X Space management 01 space extension/truncation X Chapter 4. Pointer/Name Resolution Addressing Instructions 4-8 Compare Compare Pointer Type Op Code (Hex) CMPPTRTB (CMPPTRT) (CMPPTRT) Extender Branch options Operand Indicator options Operand 2 Compare 3 [4] Branch targets operand 2 1 Compare Compare operand 18E2 Operand 1 Compare operand 1CE2 CMPPTRTI Pointer Type Indicator targets operand 2 1 Operand Data pointer, space pointer, system pointer, instruction pointer, invocation pointer, proce1: dure pointer, label pointer, or suspend pointer | | Operand Character(l) scalar or 2: Operand 3 null. [4]: • Branch Form -Instruction number, • Indicator Form - Numeric relative instruction number, branch point, or instruction pointer. variable scalar or character variable scalar. Extender compares the pointer type currently in operand 1 with the character scalar identified by operand 2. Based on the comparison, the resulting condition is used with the extender to transfer control (branch form) or to assign a value to each of the indicator operands (indi- Description: The instruction cator form). Operand 1 can specify a space pointer machine object only when operand 2 operand 2 is null or if operand 2 specifies a comparison value of hex a pointer does not exist in the storage area identified by operand 1. If Following are the allowable values for operand Hex Hex Hex Hex Hex Hex Hex Hex Hex | | | | 00 01 02 03 04 05 06 07 08 — — — — — — — A pointer does not System pointer Space pointer 00, is null. an equal condition occurs if 2: exist at this location Data pointer Instruction pointer Invocation pointer Procedure pointer Label pointer Suspend pointer Resultant Conditions « Equal - Not equal Authorization Required • Retrieve — Contexts referenced for address resolution Chapter 4. Pointer/Name Resolution Addressing Instructions 4-9 Compare Pointer Type (CMPPTRT) Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 06 01 08 Space addressing violation X X X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X X X X X X X X Parameter reference violation Authorization Unauthorized for operation X Damage encountered 44 damage Partial X state damaged object system object damage X X X X X Invalid lock state Machine-dependent exception X Machine support 02 Machine check X 03 Function check X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 01 24 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X X X X X limit 01 user profile storage limit 32 X X 03 Machine storage limit exceeded 22 X Lock state 01 20 Other Argument/parameter 05 authority verification terminated due to 1C 4 X 04 System object 1 3 X 01 10 2 02 Boundary alignment 01 0A 1 Addressing exceeded X Scalar specification 03 Scalar value invalid X Chapter 4. Pointer/Name Resolution Addressing Instructions 4-10 Compare Pointer Type (CMPPTRT) Operands Exception 36 1 2 3 4 Other Space management 01 X space extension/truncation Chapter 4, Pointer/Name Resolution Addressing Instructions 4-11 Copy Bytes with Pointers (CPYBWP) Copy Bytes with Pointers (CPYBWP) Op Code Operand (Hex) 0132 | | 2 Source Operand 1: Character variable scalar, space pointer, data pointer, system pointer, instruction pointer, invocation pointer, procedure pointer, label pointer, or suspend pointer Operand | Operand 1 Receiver 2: Character variable scalar, space pointer, data pointer, system pointer, instruction pointer, invocation pointer, procedure pointer, label pointer, suspend pointer, or null Description: This instruction copies either the pointer value or the byte string specified for the source operand depending upon whether or not a space pointer machine object is specified as one of the operands. operand If either into the receiver operand is a character variable scalar, it can have a length as great as 16776191 bytes. Operations involving space pointer machine objects perform a pointer value copy operation for only space pointer values or the pointer does not exist state. Due to this, a space pointer machine object may only be specified as an operand in conjunction with another pointer or a null second operand. The pointer does not exist state is copied from the source to the receiver pointer without signaling the pointer does not exist (hex 2401) exception. Source pointer data objects must either be not set or contain a space pointer value when being copied into a receiver space pointer machine object. Receiver pointer data objects will be set with either the system default pointer does not exist value or the space pointer value from a source space pointer machine object. Normal pointer alignment checking is performed on a pointer data object specified as an operand in conjunction with a space pointer machine object. Operations not involving space pointer machine objects, those involving just data objects as operands, perform a byte string copy of the data for the specified operands. The value of the byte string specified by operand 2 is copied to the byte string specified by operand 1 (no padding done). The byte string identified by operand 2 can contain the storage forms Normal pointer alignment checking is not done. of both scalars and pointers. \hen the Override Program Attributes (OVRPGATR) instruction is not used to override CPYBWP, the only alignment requirement is that the space addressability alignment of the two operands must be to the same position relative to a 16-byte multiple boundary. A boundary alignment (hex 0602) exception is signaled if the alignment is incorrect. The pointer attributes of any complete pointers in the source are preserved if they can be completely copied into the receiver. Partial pointer storage forms are copied into the receiver as scalar data. Scalars in the source are copied to the receiver as scalars. When the OVRPGATR instruction is used to override this instruction, the alignment requirement is the space addressability alignment of the two operands is the same relative to 16-byte multiple boundary, then this instruction will work the same as stated above. If the space addressability removed. alignment If is different, then this instruction pointer attributes of any complete pointers If a pointer data object work like a Copy Bytes Left Adjusted (CPYBLA) and the the source are not preserved in the receiver. will in operand contains a data pointer value upon execution of the instruction, the copied rather than the scalar described by the data pointer value. The character variable scalar reference allowed on either operand cannot be described through a data pointer pointer storage form is value. Chapter 4. Pointer/Name Resolution Addressing Instructions 4-12 Copy Bytes with Pointers (CPYBWP) equal to the length of the shorter of the two operands. The copying begins with the two operands left-adjusted and proceeds until completion of the shorter operand. The length of the operation Operand can specify a space pointer machine object only when operand 1 is 2 is a space pointer or null. must define a pointer reference; otherwise, an invalid operand type (hex pointer 2A06) exception is signaled by the Create Program instruction. When operand 2 is null, the value. identified by operand 1 is set to the system default pointer does not exist If operand 2 is null, operand 1 Exceptions Operands 06 2 X X 02 Boundary alignment X X 03 Range X X 06 Optimized addressability invalid X X X X X X X X X X Addressing 01 08 Space addressing violation Argument/parameter 01 10 Parameter reference violation Damage encountered 04 System object damage state 44 1C Partial system object damage Machine-dependent exception X 03 machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X Object access X X 02 Object destroyed X X 03 Object suspended X X 01 Object not found X 08 object compressed 24 Pointer specification 01 Pointer does not exist 02 Pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 36 Other 1 Exception X exceeded Space management 01 X space extension/truncation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-13 Resolve Data Pointer (RSLVDP) Resolve Data Pointer (RSLVDP) Op Code (Hex) Operand 0163 1 Operand Operand Program 2 Pointer for Data object iden- addressability to tification 3 data object Operand 1: Operand 2: Character(32) scalar (fixed-length) or Operand 3: System pointer or Data pointer. returned in data pointer with addressability to and the attributes of an external scalar data element the storage area identified by operand 1. The following describes the instruction's func- when operand tion If null. A Description: is null. operand 2 is null: does not contain a data 1 pointer, an exception is signaled. the data pointer specified by operand 1 is not resolved and has an initial value declaration, the instruction resolves the data pointer to the external scalar that the initial value describes The initial value defines the external scalar to be located and, optionally, defines the program in which it is to be located. If the program name is specified in the initial value, only that program's activation entry is searched for the external scalar. If no program is specified, programs associated with the activation entries in the current activation group in which the program is executing are searched in reverse order of the activation entries, and operand 3 is ignored The current activation group for non-bound programs is the default activation group whose state is the same as the state of the process at the time the instruction is run. If * the data pointer is c ^rently resolved and defines an existing scalar, the instruction causes no operation, and no exception is signaled. lf The following describes the A data 1. pointer that Operand Operand searched vations 2 is instruction's function when operand 2 is not null: resolved to the external scalar identified by operand 2 is returned in operand a 32-byte value that provides the name of the external scalar to be located. is 3 specifies a system pointer that for the external scalar definition. identifies the If operand program whose activation 3 is null, the instruction is to searches be all acti- the activaction group from which the instruction is executed, starting with the most recent activation and continuing to the oldest. The activation under which the instruction is issued also participates in the search. If operand 3 is not null, the instruction searches the activation of the program addressed by the system pointer. in Authorization Required • Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize - Contexts referenced for address resolution Exceptions Chapter 4. Pointer/Name Resolution Addressing Instructions 4-14 Resolve Data Pointer (RSLVDP) Operands 06 Space addressing violation 02 Boundary alignment 03 Range X 04 External data object not found 06 Optimized addressability invalid 08 Argument/parameter 01 0A Parameter reference violation Authorization 01 10 Damage encountered damage 44 Partial X state 05 authority verification terminated due to damaged X X X object X system object damage X X X X Lock state 01 1C X X Unauthorized for operation 04 System object 1A Other XXX XXX XXX XXX XXX Addressing 01 3 2 1 Exception X Invalid lock state Machine-dependent exception 03 Machine storage limit exceeded 20 22 Machine support 02 Machine check X 03 Function check X XXX XXX XXX Object access 01 Object not found 02 Object destroyed 03 Object suspended 24 07 authority verification terminated due to destroyed object X 08 object compressed X XXX XXX Pointer specification 01 Pointer does not exist 02 Pointer type invalid X 04 Pointer not resolved 2E Resource control limit 01 user profile storage limit 32 XXX Scalar specification 01 36 X exceeded Scalar type invalid 02 Scalar attributes invalid X 03 Scalar value invalid X Space management Chapter 4. Pointer/Name Resolution Addressing Instructions 4-15 Resolve Data Pointer (RSLVDP) Operands Exception 1 01 space extension/truncation 2 3 Other X Chapter 4, Pointer/Name Resolution Addressing Instructions 4-16 Resolve System Pointer (RSLVSP) Resolve System Pointer (RSLVSP) Op Code Operand (Hex) Operand 1 0164 Operand 2 Operand 4 3 addressability to Object identification and required Context through which objects is to object authorization be located Pointer for Operand 1: System Operand 2: Character(34) scalar (fixed-length) or Operand 3: System pointer or Operand 4: Character^) scalar (fixed-length) or Authority to be set 1 pointer. null. null. null. access RSLVSP ( var ptr_to_object var obji d_and_authreq system pointer-, aggregate-, OR null operand-, var context system pointer-, OR var authori ty_to_set null operand-, aggregate OR null operand ) This instruction locates an object identified by a symbolic address and stores the object's addressability and authority 1 in a system pointer. A resolved system pointer is returned in operand 1 process with addressability to a system object and the requested authority currently available to the Description: for the object. The ownership Note: Operand 2 specifies the context to be First, never set symbolic identification of the object to be located. Operand The following describes the If • |f operand 1 the system pointer. 3 identifies the in sets the appropriate authority states • in order to locate the object. Operand 4 identifies the authority states to be set the instruction locates an object based on operands 2 and 3. Then, the instruction searched the pointer. in flag is in the system pointer. instruction's function when operand does not contain a system pointer, an exception 2 is null: is signaled. the the system pointer specified by operand 1 is not resolved but has an initial value declaration, initial instruction resolves the system pointer to the object that the initial value describes. 1 he value defines the following: - Object to be located (by type code subtype code and object name) - Context to be searched to locate the object (optional) - Minimum If a context ignored. i , , If is required authorization required for the object referenced to locate the object, and operand 3 is specified, the context(s) located by the process name resolution list specified, only that context no context is Programs executing in user-domain ignored and no exception is raised. may is not assign authority in the resulting system pointer. Chapter 4. The value in operand 4 Pointer/Name Resolution Addressing Instructions is is 4-17 Resolve System Pointer (RSLVSP) used to locate the object, and operand 3 is ignored. If the object is of a type that can only be addressed through the machine context, then only the machine context is searched, and the context If the (if any) identified in the initial value or identified in operand 3 is ignored. minimum required authorization in the initial value is not set (binary 0), the instruction resolves the operand 1 system pointer to the first object encountered with the designated type code, subtype code, and object name without regard to the authorization available to the process for the object. If one or more authorization (or ownership) states are required (signified by binary 1 s), the context(s) is searched until an object is encountered with the designated type, subtype, and name and for which the process currently has all required authorization states. the system pointer specified by operand 1 is currently resolved to address an existing object, the does not modify the addressability contained in the pointer and causes only the authority attribute in the pointer to be modified based on operand 4. If instruction operand If in * * 2 is not null, the operand 1 system pointer is resolved to the object identified by operand 2 the context(s) specified by operand 3. The format of operand 2 is as follows: Object specification — Type code - Subtype code — Object Char(32) Char(1) Char(1) name Char(30) Required authorization — Object control - Object — (1 = required) Char(2) management Authorized pointer - Space Retrieve — Insert — Delete — Update — Ownership Bit 1 Bit 3 Bit 4 Bit 5 Bit 6 Bit 7 Bit 8 - Excluded - Authority List — Reserved (binary Bit 9 Management Bit 0) The allowed type codes are as Hex 01 Hex 02 Hex 03 Hex 04 Hex 06 Hex 07 Hex 08 Hex 09 Hex 0A Hex 0B Hex 0C Hex 0D Hex 0E 0 Bit 2 authority - Bit 10 Bit 11-15 follows: = Access group = Program = Module = Context = Byte string space = Journal space = User profile = Journal port = Queue = Data space = Data space index = Cursor = Index Chapter 4. Pointer/Name Resolution Addressing Instructions 4-18 Resolve System Pointer (RSLVSP) Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex All OF 10 11 = Commit block = Logical unit description = Network description = = 14 = 15 = 16 = 17 = 18 = 19 = 1A = IB = 12 13 1C Controller description Dump space Class of Service Description Mode description Network interface description Connection list Queue space Space Process control space Authorization = list Dictionary other codes are reserved. If other codes are specified, they cause a scalar value invalid (hex 3203) exception to be signaled. which to locate the object identified by operand 2. If operand 3 is process name resolution list are searched in the order in which null, the system pointer specified must address a context, 3 is not they appear in the list. If operand object. If the object is of a type that can only be addressed and only this context is used to locate the through the machine context, then only the machine context is searched, and operand 3 and the Operand 3 identifies the context in null, then the contexts identified in the process If name resolution are ignored. list the required authorization field in operand 2 is not set (all values set to 0), the instruction resolves the operand 1 system pointer to the first object encountered with the designated type code subtype code and object name without regard to the authorization currently available to the process. If one or more authorization (or ownership) states are required (signified by binary 1's), the context is searched until an object is encountered with the designated type code, subtype code, object name, and the user , , profiles Once governing the instruction's execution that have addressability has been set in the required authorization states. all the pointer, operand 4 is used to determine which, if any, of the Only the object authority states correlating with to be set into the pointer. object control through update can be set into the pointer. This restriction applies whether the authority mask controlling which authorities to set in the pointer comes from operand 4, operand 2, or the initial value for the system pointer. object authority states bits 0 through 7, that is is, , the object authority states required to locate the object are set in the pointer. This required object authority is as specified in operand 2 or in the initial value for operand 1 if operand 2 is is null. If the process does not currently have authorized pointer authority for the object, no authority If operand 4 stored If in is null, the system pointer, and no exception operands 2 and 4 are null and operand 1 is is signaled. a resolved system pointer, the authority states in the pointer are not modified. operand 4 is not null, it specifies the object authority states to be set The format of operand 4 is as follows: If • Requested authorization — Object control — Object - Authorized pointer — Space (1 = in the resolved system pointer. Char(2) set authority) Bit 0 management Bit 1 Bit 2 Bit 2 authority Chapter 4. Pointer/Name Resolution Addressing Instructions 4-19 Resolve System Pointer (RSLVSP) Retrieve Bit 4 Insert Bit 5 Delete Bit 6 Update Bit 7 Reserved (binary The authority states set 0) in Bits 8-15 the resolved system pointer are based on the following: The authority already stored in the pointer can be increased only when the process has authorized pointer authority to the referenced object. If this authority is not available and the pointer was resolved by this instruction, the authority in the operand 1 system pointer is set to the not set state, and no exception is signaled. If operand 2 is null, if operand 1 is a resolved system pointer con- and if authorized pointer authority authorities cannot be stored in the pointer. taining authority, is not available to the process, additional the process does not currently have all the authority states requested in operand requested and available states are set in the pointer, and no exception is signaled. If Note that the authority stored this instruction stored in when operand in 4, only the the operand 2 is null 1 system pointer is a source of authority applies to and operand 1 is a resolved system pointer with authority it. Authorization Required • Retrieve — Contexts referenced for address resolution (including operand 3) Lock Enforcement 8 Materialization - Contexts referenced for address resolution (including operand 3) Exceptions Operands Exception 06 4 Space addressing violation X X X X X X X X 03 Range X X X X 06 Optimized addressability invalid X X X X Other X X X X Argument/parameter Parameter reference violation Authorization 01 10 3 02 Boundary alignment 01 0A 2 Addressing 01 08 1 Unauthorized for operation X X Damage encountered 02 Machine context 04 System object damage damage state 05 authority verification terminated due to 44 Partial X state X damaged system object damage 4. X X object X X X Chapter X X X X X Pointer/Name Resolution Addressing Instructions 4-20 Resolve System Pointer (RSLVSP) Operands Exception 1A 22 3 4 X Invalid lock state X 02 Machine check X 03 Function check X Object access Object not found X X X X 02 Object destroyed X X X X 03 Object suspended X X X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 Pointer does not exist 02 Pointer type invalid X X X X X X X X X 04 Pointer not resolved 2E Resource control limit 01 user profile storage limit 32 36 Other Machine support 01 24 2 Lock state 01 20 1 X exceeded Scalar specification 02 Scalar attributes invalid X X 03 Scalar value invalid X X Space management 01 X space extension/truncation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-21 Set Space Pointer from Pointer (SETSPPFP) Set Space Pointer from Pointer (SETSPPFP) Op Code (Hex) Operand 0022 Operand 1 Receiver Operand /: Operand 2: Space 2 Source Pointer pointer. Data pointer, system pointer, or space pointer. Description: A space pointer is returned the pointer specified by operand 2. The meaning of the pointers allowed Pointer for in operand operand 2 is 1 with the addressability to a space object from as follows: Meaning The space pointer returned in operand string addressed by the source pointer Data pointer or space pointer System pointer 1 is for set to address of the leftmost byte of the byte operand 2. The space pointer returned in operand 1 is set to address the first byte of the space contained in the system object addressed by the system pointer for operand 2. The space object addressed is either the created system space or an associated space for the system object addressed by the system pointer. If the operand 2 system pointer addresses a system object with no associated space, the invalid space reference (hex 0605) exception is signaled. The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are not signaled when operand and operand 2 are space pointer machine objects. This occurs when operand 2 contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, operand 1 is set with an internal machine value that preserves the exception condition that existed for operand 2. The appropriate exception condition will be signaled for either pointer when a subsequent attempt is made to reference the space data that the 1 pointer addresses. Authorization Required • Space authority — Operand ° 2 (if a system pointer) Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 06 1 2 Other Addressing 01 space addressing violation X X 02 boundary alignment X X 03 range X X Chapter 4, Pointer/Name Resolution Addressing Instructions 4-22 Set Space Pointer from Pointer (SETSPPFP) Operands 1 Exception 04 external data object not found 2 Other X X 01 invalid space reference 05 X 06 optimized addressability invalid X 01 08 Argument/parameter X parameter reference violation 0A Authorization X unauthorized for operation 10 Damage encountered 04 system object damage state 05 authority verification terminated due to damaged object 44 1A partial system object damage XXX XXX X Lock state X 01 invalid lock state 1C Machine-dependent exception 03 machine storage 20 22 X exceeded Machine support 02 machine check X 03 function check X Object access found X X 02 object destroyed X X 03 object suspended X X 01 object not 24 limit 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid Resource control X X limit 01 user profile storage limit 36 X X 03 pointer addressing invalid object 2E X X exceeded Space management 01 X space extension/truncation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-23 Set System Pointer from Pointer (SETSPFP) Set System Pointer from Pointer (SETSPFP) Op Code (Hex) Operand 0032 Operand 2 Source pointer 1 Receiver Operand 1: System pointer. Operand 2: System pointer, Description: space pointer, data pointer, or instruction pointer. This instruction returns a system pointer to the system object address by the supplied pointer. If operand 2 is a system pointer, then a system pointer addressing the same object operand 1 containing the same authority as the input pointer. operand If 2 is a is returned in space pointer or a data pointer, then a system pointer addressing the system object space addressed by operand 2 is returned in operand 1. that contains the associated If operand 2 is an instruction pointer, then a system pointer addressing the program system object that contains the instruction addressed by operand 2 is returned in operand 1. operand If 2 is an unresolved system pointer or data pointer, the pointer is resolved first. Authorization Required 8 Retrieve - Contexts referenced for address resolution Lock Enforcement 8 Materialization - Contexts referenced for address resolution Exceptions Operands Exception 1 06 01 08 space addressing violation X X 02 boundary alignment X X 03 range X X 04 external data object not found X X 06 optimized addressability invalid X X parameter reference violation Authorization 01 unauthorized for operation 10 Other Argument/parameter 01 0A 2 Addressing X Damage encountered 02 machine context 04 system object damage damage XXX X state Chapter 4. Pointer/Name Resolution Addressing Instructions 4-24 Set System Pointer from Pointer (SETSPFP) Operands Exception 05 authority verification terminated due to 44 1 partial 1 damaged X system object damage X 22 X Machine-dependent exception X Machine support 02 machine check X 03 function check X Object access X 01 object not found 24 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X exceeded Scalar specification X 01 scalar type invalid 36 X limit 01 user profile storage limit 32 X Lock state 03 machine storage limit exceeded 20 Other X 01 invalid lock state 1C 2 object X Space management 01 X space extension/truncation Chapter 4. Pointer/Name Resolution Addressing Instructions 4-25 Space Addressing Instructions Chapter 5. Space Addressing Instructions This chapter describes the instructions used for space addressing. betic order. For an alphabetic summary of all These instructions are the instructions, see Appendix A, in alpha- “Instruction Summary” Add Space Pointer (ADDSPP) Compare Space Addressability (CMPSPAD) 5-3 Set Data Pointer (SETDP) 5-7 Set Data Pointer Addressability (SETDPADR) 5-5 5-9 Set Data Pointer Attributes (SETDPAT) 5-11 Set Space Pointer (SETSPP) 5-14 Set Space Pointer with Displacement (SETSPPD) 5-16 Set Space Pointer Offset (SETSPPO) 5-18 Store Space Pointer Offset (STSPPO) 5-20 Subtract Space Pointer Offset (SUBSPP) 5-22 Subtract Space Pointers For Offset © Copyright IBM Corp. 1991, 1993 (SUBSPPFO) 5-24 5-1 Space Addressing Instructions Chapter 5. Space Addressing Instructions 5-2 Add Space Pointer (ADDSPP) Add Space Op Code Pointer (ADDSPP) Operand (Hex) 0083 1 Receiver Pointer Operand 7: Space pointer. Operand 2: Space pointer. Operand 3: Binary scalar. Operand 2 Source Pointer Operand 3 Increment Description: This instruction adds a signed or unsigned binary value to the offset of a space pointer. The value of the binary scalar represented by operand 3 is added to the space address contained in the space pointer specified by operand 2, and the result is stored in the space pointer identified by operand 1. I.e. Operand 1 = Operand 2 + Operand 3 Operand 3 can have a positive or negative value. The space object not changed by the instruction. that the pointer is addressing is Operand 2 must contain a space pointer when the execution of the instruction is initiated; otherwise, an invalid pointer type (hex 2402) exception is signaled. When the addressability in a space pointer is modified, the instruction signals a space addressing (hex 0601) exception only when the space address to be stored in the pointer has a negative offset value or when the offset addresses beyond the largest space allocatable in the object. This maximum offset value is dependent on the size and packaging of the object containing the space and is independent of the actual size of the space allocated. If the exception is signaled by this instruction for this reason, the pointer is not modified by the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent of the space cause the space addressing (hex 0601) exception to be signaled. The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are not signaled when operand 1 and operand 2 are space pointer machine objects. This occurs when operand 2 contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, operand 1 is set with an internal machine value that preserves the exception condition that existed for operand 2. The appropriate exception condition will be signaled for either pointer when a subsequent attempt is made to reference the space data that the pointer addresses. Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 2 1 Addressing 3 [4-6] Other XXX XXX XXX XXX Argument/parameter Chapter 5. Space Addressing Instructions 5-3 Add Space Pointer (ADDSPP) Operands XXX XXX XXX Exception 01 10 1 parameter reference violation Damage encountered 04 system object 44 1C partial damage state system object damage 2 3 [4-6] 22 X 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access found 02 object destroyed 03 object suspended 08 object compressed Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X limit 01 user profile storage limit 36 X Machine support 01 object not 24 X Machine-dependent exception 03 machine storage limit exceeded 20 Other X exceeded Space management 01 space extension/truncation X Chapter 5. Space Addressing Instructions 5-4 Compare Space Compare Space Op Code Addressability (Hex) Extender Branch options CMPSPADB 1CF2 Indicator options 18F2 (CMPSPAD) (CMPSPAD) Operand Operand 1 Compare operand CMPSPADI Addressability 3 [4-6] Branch targets operand 2 1 Compare operand Operand 2 Compare Compare Indicator targets operand 2 1 Operand 1: Numeric variable scalar, character variable scalar, numeric variable array, character variable array, pointer data object, pointer data object array. Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character variable array, pointer data object, pointer data object array. Operand 3 [4-6]: • Branch Form-Instruction number, ® Indicator relative instruction number, branch Form-Numeric variable scalar or character variable Description: scalar. The space addressability of the object specified by operand addressability of the object specified by operand Based on the point, or instruction pointer. 1 is compared with the space 2. results of the comparison, the resulting condition is used with the extender to transfer each of the indicator operands (indicator form). If the operands are not in the same space, the resultant condition is unequal. If the operands are in the same space and the offset of operand 1 is larger or smaller than the offset of operand 2, the resultant condition is high or low, respectively. Equal occurs only if the operands are in the same space at the same offset. Therefore, the resultant conditions (high, low, equal, and unequal) are mutually exclusive. Consequently, if you specify that an action be taken upon the nonexistence of a condition, this results in the action being taken upon the occurrence of any of the other three possible conditions. For example, a branch not high would result in the branch being taken on a low, equal, or unequal condi- control (branch form) or to assign a value to tion. a pointer data object operand contains a data pointer value upon execution of the instruction, the is compared to the pointer data object rather than to the scalar described by the data If addressability pointer value. The variable scalar references allowed on operands 1 and 2 cannot be described through a data pointer value. The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are not signaled when operand 1 or operand 2 is based on a space pointer machine object. This occurs when the space pointer machine object contains an internal machine value that indicates one of these error conditions exists. comparison operation is If the corresponding exception not defined other than that it is will not signaled, the resulting condition of the be one of the four valid resultant conditions for this instruction. Resultant Conditions 8 High • Low 8 Equal 8 Unequal Chapter 5. Space Addressing Instructions 5-5 Compare Space Addressability (CMPSPAD) Exceptions Operands Exception 06 1 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object 44 1C partial damage 2 3 [4-6] XXX XXX XXX XXX XXX XXX XXX Addressing state system object damage Other X X Machine-dependent exception 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X XXX XXX XXX XXX XXX Object access 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 36 exceeded X Space management 01 space extension/truncation X Chapter 5. Space Addressing Instructions 5-6 Set Data Pointer (SETDP) Set Data Pointer (SETDP) Op Code Operand (Hex) 0096 Operand 1 Receiver Operand 1: Operand 2: 2 Source Data pointer. Numeric variable scalar, character variable scalar, numeric variable array, or character variable array. A data pointer is created and returned in the storage area specified by operand 1 and has the attributes and space addressability of the object specified by operand 2. Addressability is set to the low-order (leftmost) byte of the object specified by operand 2. The attributes given to the data pointer include scalar type and scalar length. Description: operand If compound operand, 2 is a substring the length attribute is set equal to the length of the operand 2 is a subscript compound operand, the attributes and addressability of the single array element specified are assigned to the data pointer. If operand 2 is an array, the attributes and addressability of the first element of the array are assigned to the data pointer. A data pointer can only be set to describe an element of a data array, not a data array in its entirety. substring. When If the addressability (hex 0601) exception 9 • When the data pointer is modified, the instruction signals the space addressing of the following conditions occurs: the space address to be stored in the pointer would have a negative offset value. When the offset would address an area beyond the largest space allocatable in the object. This maximum offset value is dependent on the size and packaging of the object containing the space and If in when one is independent of the actual size of the space allocated. the exception is signaled by this instruction for one of these reasons, the pointer is not modified by the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent cause the space addressing (hex 0601) exception to be signaled. Exceptions Operands Exception 06 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Addressing 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered XXX XXX 04 system object damage state 44 1C Other partial system object damage Machine-dependent exception 03 machine storage limit exceeded Chapter 5. Space Addressing Instructions 5-7 Set Data Pointer (SETDP) Operands Exception 20 22 1 2 02 machine check X 03 function check X Object access X 01 object not found 02 object destroyed X X 03 object suspended X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 36 Other Machine support exceeded X Space management 01 space extension/truncation X Chapter 5. Space Addressing Instructions 5-8 Set Data Pointer Addressability (SETDPADR) Set Data Pointer Addressability Op Code Operand (Hex) 0046 1 Receiver Operand 7: Operand 2: (SETDPADR) Operand Source 2 Data pointer. Numeric variable scalar, character variable scalar, numeric variable array, or character variable array. The space addressability of the object specified for operand 2 is assigned to the data pointer specified by operand 1. If operand 1 contains a resolved data pointer, the data pointer's scalar attribute component is not changed by the instruction. If operand 1 contains an initialized but unre- Description: solved data pointer, the data pointer the pointer. If operand 1 is resolved in order to establish the scalar attribute component of contains other than a resolved data pointer, the instruction creates and returns a data pointer in operand 1 with the addressability of the object specified for operand the instruction establishes the attributes as a character(l) scalar. 2, and When the addressability is set into a data pointer, the space addressing (hex 0601) exception is signaled by the instruction only when the space address to be stored in the pointer has a negative offset value or if the offset addresses beyond the largest space allocatable in the object. This maximum offset value is dependent on the size and packaging of the object containing the space and is independent of the actual size of the space allocated. If the exception is signaled for this reason, the is not modified by the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent of the space cause the space addressing (hex 0601) exception to be signaled. pointer Exceptions Operands Exception 06 space addressing violation X X X X 03 range X X 04 external data object not found X 06 optimized addressability invalid X X X X parameter reference violation Damage encountered 04 system object 44 1C partial damage 22 XXX XXX state system object damage Machine-dependent exception 03 machine storage 20 Other Argument/parameter 01 10 2 02 boundary alignment 01 08 1 Addressing limit exceeded Machine support 02 machine check X 03 function check X Object access Chapter 5. Space Addressing Instructions 5-9 Set Data Pointer Addressability (SiTDPADR) Operands Exception 1 2 01 object not found X X 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 36 Other exceeded X Space management 01 X space extension/truncation Chapter 5. Space Addressing Instructions 5-10 Set Data Pointer Attributes (SETDPAT) Set Data Pointer Attributes (SETDPAT) Op Code Operand (Hex) 004A Operand 1 Receiver 2 Attributes Operand 1: Data pointer. Operand 2: Character(7) scalar. operand 2 is interpreted as an encoded assigned to the attribute portion of the data pointer specified by operand 1. The addressability portion of the data pointer is not modified. If operand 1 contains an initialized but unresolved data pointer, the data pointer is resolved in order to establish the addressability in the pointer. The attributes specified by the instruction are then assigned to the data pointer. If operand 1 does not contain a data pointer at the initiation of the instruction's execution, an exception The value Description: of the character scalar specified by representation of an attribute set that is signaled. is The format of the • attribute set as follows: is Data pointer attributes Char(7) — Char(1) Scalar type Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex — 00 = Signed binary 01 = Floating-point 02 = Zoned decimal 03 = Packed decimal = Character = Onlyns = Onlys = Either 04 06 07 08 = Open 0A = Unsigned binary 09 Bin{2) Scalar length If binary or character: - If - Fractional digits (F) Bits 0-7 - Total digits (T) Bits 8-15 1 <T< 31, 0 < F < T) character: Length (L, where 1 < L < 32767) (L, where 1 < L < 16,383) Onlyns: - Length L If 8 for floating-point) zoned decimal or packed decimal: - If or 4 for binary) Length (only 4 or (where If 2 floating-point: - If Length (only is the number of double-byte characters. Onlys: - Length (L, where 2 < L < 32,766) Chapter 5. Space Addressing Instructions 5-11 Set Data Pointer Attributes (SETDPAT) is the L is even • L includes Length - of bytes any SO and SI characters where (L, < number the • L • L includes is 1 any L < 32,766) of bytes SO and SI characters. Open: Length - - L Either: If If number • • where (L, the 2 number • L • L includes any is Reserved (binary < L < 32,766) of bytes SO and SI characters. 0) Bin(4) usage of a Data Pointer describing an Onlyns, Onlys, Either, or Open scalar value is limited Left Adjusted With Pad instruction. Usage of such a data pointer defined value on any other instruction is not supported and results in the signaling of the scalar type Support to the for Copy Extended Characters invalid (hex 3201) exception. Exceptions Operands Exception 06 08 2 01 space addressing violation X X 02 boundary alignment X X 03 range X X 04 external data object not found X 06 optimized addressability invalid X X X X X X X X X X Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object damage state 44 1C partial system object damage Machine-dependent exception 03 machine storage 20 22 limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 08 object compressed 24 Other 1 Addressing X Pointer specification Chapter 5. Space Addressing Instructions 5-12 Set Data Pointer Attributes (SETDPAT) Operands Exception 01 pointer does not exist 02 pointer type invalid 2E Resource control X X Other X exceeded Scalar specifications 01 scalar type invalid 36 2 X limit 01 user profile storage limit 32 1 X X 02 scalar attributes invalid X 03 scalar value invalid X Space management 01 space extension/truncation X Chapter5. Space Addressing Instructions 5-13 Set Space Pointer (SETSPP) Set Space Pointer (SETSPP) Op Code Operand (Hex) 0082 1 Receiver Operand 1\ Space Operand 2 Source pointer. Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character variable array, or pointer data object. A space pointer is returned in operand byte of the byte string identified by operand 2. Description: When 1 and is set to address the lowest order (leftmost) the addressability is set in a space pointer, the instruction signals the space addressing (hex the offset addresses beyond the largest space allocatable in the object or when the space address to be stored in the pointer has a nonpositive offset value. This offset value is dependent on the size and packaging of the object containing the space and is independent of the 0601) exception when actual size of the space allocated. If the exception is signaled for this reason, the pointer is not modiby the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent of the space cause the space addressing (hex 0601) exception to be signaled. fied a pointer data object specified for operand 2 contains a data pointer value upon execution of the is set to the pointer storage form rather than to the scalar described by the data pointer value. The variable scalar references allowed on operand 2 cannot be described If instruction, the addressability through a data pointer value. The object destroyed (hex 2202) exception, the optimized addressability invalid (hex 0606) exception, the parameter reference violation (hex 0801) exception, and the pointer does not exist (hex 2401) exception are not signaled when operand 1 is a space pointer machine object and operand 2 is based on a space pointer machine object. This occurs when the basing space pointer machine object for operand 2 contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, operand 1 is set with an internal machine value that preserves the exception condition which existed for operand 2. The appropriate exception condition is signaled for either pointer upon a subsequent attempt to reference the space data the pointer addresses. Exceptions Operands Exception 06 01 08 space addressing violation X X X X 03 range X X 06 optimized addressability invalid X X Other X X Argument/parameter parameter reference violation Damage encountered 04 system object 44 1C 2 02 boundary alignment 01 10 1 Addressing partial damage XXX XXX state system object damage Machine-dependent exception Chapter 5. Space Addressing Instructions 5-14 Set Space Pointer (SETSPP) Operands Exception 03 machine storage 20 22 1 limit 2 Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X exceeded Scalar specification X 01 scalar type invalid 36 X limit 01 user profile storage limit 32 Other X exceeded X Space management 01 X space extension/truncation Chapter 5. Space Addressing Instructions 5-1 Set Space Pointer with Displacement (SETSPPD) Set Space Pointer with Displacement (SETSPPD) Op Code Operand (Hex) 0093 1 Receiver Operand /: Space Operand Source 2 Operand 3 Displacement pointer. Operand 2: Numeric variable scalar, character variable scalar, numeric variable array, character variable array, or pointer data object. Operand 3: Binary scalar. A space pointer is returned in operand 1 and is set to the space addressability of the lowest (leftmost) byte of the object specified for operand 2 as modified algebraically by an integer displacement specified by operand 3. Operand 3 can have a positive or negative value. I.e. Description: Operand When 1 = Address_of (Operand 2) + Operand the addressability is set in a space pointer, the instruction signals the space addressing (hex the space address to be stored in the pointer has a negative offset value or the offset addresses beyond the largest space allocatable in the object. This maximum offset 0601) exception when 3 when value is dependent on the size and packaging of the object containing the space and is independent of the actual size of the space allocated. If the exception is signaled for this reason, the pointer is not modified by the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent of the space cause the space addressing (hex 0601) exception to be signaled. a pointer data object specified for operand 2 contains a data pointer value upon execution of the is set to the pointer storage form rather than to the scalar described by the data pointer value. The variable scalar references allowed on operand 2 cannot be described If instruction, the addressability through a data pointer value. The object destroyed (hex 2202) exception, the optimized addressability invalid (hex 0606) exception, the parameter reference violation (hex 0801) exception, and the pointer does not exist (hex 2401) exception are not signaled when operand 1 is a space pointer machine object and operand 2 is based on a space pointer machine object. This occurs when the basing space pointer machine object for operand 2 contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, operand 1 is set with an internal machine value that preserves the exception condition which existed for operand 2. The appropriate exception condition is signaled for either pointer upon a subsequent attempt is made to reference the space data the pointer addresses. Exceptions Operands Exception 06 01 08 1 2 Other Addressing space addressing violation X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X Argument/parameter Chapters. Space Addressing Instructions 5-16 Set Space Pointer with Displacement (SETSPPD) Operands Exception 01 parameter reference violation 10 2 Other X X X X X X X X X X Damage encountered 04 system object damage state 44 1C 1 X partial system object damage Machine-dependent exception X 03 machine storage limit exceeded 20 22 Machine support 02 machine check X 03 function check X Object access 01 object not found X X X 02 object destroyed X X X 03 object suspended X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X X limit 01 user profile storage limit 36 X X exceeded Space management 01 X space extension/truncation Chapter 5. Space Addressing Instructions 5-17 Set Space Pointer Offset (SETSPPO) Set Space Pointer Offset (SETSPPO) Op Code Operand (Hex) 0092 Operand Source 1 1 Receiver Operand 1: Operand 2: Space 2 pointer. Binary scalar. Description: The value of the binary scalar specified by operand 2 is assigned to the offset portion of the space pointer identified by operand 1. The space pointer continues to address the same space object. Operand must contain a space 1 pointer; otherwise, an invalid pointer type (hex 2402) exception sig- is naled. When the addressability (hex 0601) exception The space address • The • the space pointer is modified, the instruction signals a space addressing of the following conditions occurs: to be stored in the pointer has a negative offset value. addresses beyond the largest space allocatable in the object. This maximum offset dependent on the size and packaging of the object containing the space and is independent of the actual size of the space allocated. offset value If in when one is the exception is signaled by this instruction for this reason, the pointer is not modified by the instruction. Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent cause the space addressing (hex 0601) exception to be signaled. Exceptions Operands Exception 06 01 08 space addressing violation X X X X 03 range X X 06 optimized addressability invalid X X X X parameter reference violation Damage encountered 44 partial damage state system object damage XXX XXX Machine-dependent exception 03 machine storage 20 Other Argument/parameter 04 system object 1C 2 02 boundary alignment 01 10 1 Addressing limit exceeded Machine support 02 machine check X 03 function check X Chapter5. Space Addressing Instructions 5-18 Set Space Pointer Offset (SETSPPO) Operands Other 1 2 X X 02 object destroyed X X 03 object suspended X X Exception Object access 22 01 object not found X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X exceeded Scalar specification X 01 scalar type invalid 36 X limit 01 user profile storage limit 32 X X Space management 01 space extension/truncation Chapter 5. Space Addressing Instructions 5-19 Store Space Pointer Offset (STSPPO) Store Space Pointer Offset (STSPPO) Op Code (Hex) °°A2 Operand /: Operand 2: Operand 1 Receiver Operand 2 Source Binary variable scalar. Space pointer. Description: The offset value of the space pointer referenced by operand 2 variable scalar defined by operand 1. is stored in the binary If operand 2 does not contain a space pointer at the initiation of the instruction's execution, an invalid pointer type (hex 2401) exception is signaled. If binary s/ze (hex 0C0A) exceptions are to be signaled either because the program creation attribute indicated to do so or because a translator directive indicated to do so, they will be signalled under the following conditions. If the offset value is greater than 32 767 and operand 1 is a signed binary (2) scalar, a size (hex 0C0A) exception is signaled. If the offset value is greater than 65 535 and operand 1 is an unsigned binary (2) scalar, a size (hex 0C0A) exception is signaled. Exceptions Operands Exception 06 1 2 X X X X X X X X 01 X X space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0C parameter reference violation Computations 0A 10 size X Damage encountered 04 system object 44 1C partial damage XXX XXX state system object damage Machine-dependent exception 03 machine storage 20 limit exceeded Machine support 02 machine check X 03 function check 22 Other Addressing X Object access 01 object not found 02 object destroyed 03 object suspended Chapter 5 . X X X X X X Space Addressing Instructions 5-20 Store Space Pointer Offset (STSPPO) Operands 1 Exception 08 object compressed 24 does not exist 02 pointer type invalid Resource control X X X X limit 01 user profile storage limit 36 Other X Pointer specification 01 pointer 2E 2 X exceeded Space management X 01 space extension/truncation Chapter 5, Space Addressing Instructions 5-21 Subtract Space Pointer Offset (SUBSPP) Subtract Space Pointer Offset (SUBSPP) Op Code (Hex) Operand 0087 Operand 2 1 Receiver pointer Operand 1: Space pointer. Operand 2: Space pointer. Operand 3: Binary scalar. Source pointer Operand 3 Decrement The value of the binary scalar specified by operand 3 is subtracted from the space address contained in the space pointer specified by operand 2; the result is stored in the space pointer identified by operand 1. I.e. Description: Operand 1 = Operand 2 - Operand 3 Operand 3 can have a positive or negative value. The space object that the pointer is addressing is not changed by the instruction. If operand 2 does not contain a space pointer at the initiation of the instruction's execution, an invalid pointer type (hex 2402) exception he ^ (hex nl™ 0601) addreSSabllity exception in signaled. the Space pointer when one is modified, the instruction signals a space addressing of the following conditions occurs: The space address to be stored The is in the pointer has a negative offset value. addresses beyond the largest space allocatable in the object. This maximum offset dependent on the size and packaging of the object containing the space and is independent of the actual size of the space allocated. offset value If is the exception is signaled by this instruction for this reason, the pointer tir»n is not modified by the instruc*' Attempts to use a pointer whose offset value lies between the currently allocated extent of the space and the maximum allocatable extent cause the space addressing exception to be signaled. The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception parameter reference violation (hex 0801) exception, and pointer does not exist (hex 2401) exception are not signaled when operand 1 and operand 2 are space pointer machine objects. This occurs when operand 2 contains an internal machine value that indicates one of these error conditions exists If the corresponding exception is not signaled, operand 1 is set with an internal machine value that preserves the exception condition that existed for operand 2. The appropriate exception condition will be signaled for either pointer when a subsequent attempt is made to reference the space data that the pointer addresses. Exceptions 12 Operands Exception 06 Addressing 01 3 Other XXX XXX XXX XXX space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid Chapter 5. Space Addressing Instructions 5-22 Subtract Space Pointer Offset (SUBSPP) Operands Exception 08 44 partial system object damage 22 X X X X X X X X X X X Machine-dependent exception 03 machine storage 20 3 Damage encountered 04 system object damage state 1C 2 Argument/parameter 01 parameter reference violation 10 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X X 02 object destroyed X X X 03 object suspended X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X X X X X X X X X limit 01 user profile storage limit 36 Other 1 exceeded Space management 01 space extension/truncation Chapter 5, Space Addressing Instructions 5-23 Subtract Space Pointers For Offset (SUBSPPFO) Subtract Space Pointers For Offset Op Code (Hex) Operand 0033 (SUBSPPFO) Operand 2 Minuend pointer 1 Offset Difference Operand 3 Subtrahend pointer Operand 1: Operand 2: Space pointer. Operand 3: Space pointer. Binary(4) variable scalar. Description: The offset portion of the space address contained in the operand 3 space pointer is subtracted from the offset of the space address contained in the space pointer specified by operand 2; the result is stored in the 4 byte binary scalar identified by operand 1. I.e. Operand The 1 offsets for = Address_of (Operand 2) operands 2 and - Address_of (Operand 3 are strictly 3) unsigned values, while the operand result can 1 positive or negative value. have a No check is made to determine that the space pointers point to the same space. In addition, the existence of the pointers is not checked except for pointers used as a base for the operands. When the space pointers point to different spaces, or one or both of the pointer operands is subject to the pointer does not exist condition, the resulting value is undefined, but no exception is signaled. However, if both operand 2 and operand 3 are subject to the pointer does not exist condition, the result value is zero. If either operand 2 or operand 3 contains a pointer which is not a space pointer at the initiation of the instruction's execution, an invalid pointer type (hex 2402) exception is signaled. A size (hex 0C0A) exception occurs when the operand 1 field is unsigned binary, the resulting value of is negative, and the program attribute to signal size exceptions is in effect. the subtraction The object destroyed (hex 2202) exception, optimized addressability invalid (hex 0606) exception, parameter reference violation (hex 0801) exception, and pointer does not signaled when operand not exist (hex 2401) exception are and operand 3 are space pointer machine objects. This occurs when operand 2 or operand 3 contains an internal machine value that indicates one of these error conditions exists. If the corresponding exception is not signaled, operand 1 is undefined, but no exception is siga 2 naled. Exceptions Operands Exception 'I 06 Addressing 01 03 range 06 optimized addressability invalid Argument/parameter 01 3 Other XXX XXX XXX XXX XXX space addressing violation 02 boundary alignment 08 2 parameter reference violation Chapter 5. Space Addressing Instructions 5-24 Subtract Space Pointers For Offset (SUBSPPFO) Operands Exception 10 44 partial system object damage 22 Other X X X X X X X X X Machine-dependent exception 03 machine storage 20 3 Computation 0A Size 1C 2 Damage encountered 04 system object damage state oc 1 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X X 02 object destroyed X X X 03 object suspended X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X X X X X X X X limit 01 user profile storage limit 36 X exceeded Space management 01 space extension/truncation Chapter 5. Space Addressing Instructions 5-25 Space Management Instructions Chapter 6. Space Management Instructions This chapter describes the instructions used for space management. These instructions are betic order. For an alphabetic summary of ail the instructions, see Appendix A, “Instruction in alpha- Summary.” 6-3 Create Space (CRTS) Materialize Space Attributes (MATS) Modify Space Attributes (MODS) © Copyright IBM Corp. 1991, 1993 6-11 6-15 6-1 Space Management Instructions Chapter 6. Space Management Instructions 6-2 Create Space (CRTS) Create Space (CRTS) Op Code Operand 1: System Operand 2: Space — Pointer for space Operand 2 Space creation addressability template Operand (Hex) 0072 1 pointer. pointer. ILE access CRTS ( var space_obj creation_template system pointer-, space pointer : : ) A space Description: plate specified by returned is Space in object operand 2, created with the attributes that are specified in the space creation temand addressability to the created space is placed in a system pointer that is the addressing object specified by operand objects, unlike other types of 1. system objects, are used to contain a space and serve no other purposes. The template identified by operand of the space creation template: • • must be 16-byte aligned in the space. The following Template size specification Char(8)* - Bin(4)* Size of template - Number • 2 Char(32) — Object type Char(1)* — Object subtype Char(1) — Object name Char(30) Object creation options Char(4) - Bit 0 Existence attribute 1 = Temporary = Permanent - Space 0 1 - 1 - = = Bit attribute 1 1 Fixed-length Variable-length Bit 2 context Addressability is not inserted into context Addressability is inserted into context Access group 0 — = = Initial 0 the format Bin{4)* of bytes available for materialization Object identification 0 is = Do not = Create Bit 3 member of access group member of access group create as as Reserved (binary Bits 4-5 0) Chapter 6. Space Management Instructions 6-3 Create Spaee (CRTS) — Public authority specified 0 1 — Initial 0 1 owner specified Reserved (binary — Set public authority 1 — 1 — 0) Bits 8-11 in operand Bit 12 1 = No = Yes space Initialize 0 Bit 7 = No = Yes — 0 Bit 6 = No = Yes Bit 13 = Initialize = Do not initialize Automatically extend space 0 1 — Hardware storage protection level 00 = Reference and modify allowed for user state programs 01 = Only reference allowed for user state programs 10 = Invalid (yields template value invalid (hex 3801) exception) 11 = No reference or modify allowed for user state programs — 1 — • Bits 15-16 Process temporary space accounting 0 = The = The temporary space temporary space Reserved (binary Bit 17 will be tracked to the creating process will not be tracked to the creating process 0) Bits 18-31 Recovery options — 14 Bit = No = Yes Reserved (binary Char(4) Char(2) 0) — ASP number Char(2) • Size of space Bin(4) • Initial • Performance class value of space Char(1) Char(4) — Space alignment 0 — The space associated Bit 0 with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space. If no space is specified for the object, this value must 1 — = be specified for the performance class. The space associated with the object is allocated to allow proper alignment of pointers 16-byte alignments within the space as well as to allow proper alignment of input/output buffers at 512-byte alignments within the space. Clear the space into main memory Bit at 1 during creation 0 = Only a minimum amount (up to 4K) of the space will be in main storage upon completion of the instruction. 1 = Most of the space, with some completion of the instruction. limits enforced by the machine, Chapter 6. will be in main storage upon Space Management Instructions 6-4 Create Space (CRTS) — Reserved (binary — Main storage pool selection Bit 5 = Process default main storage pool is used for object. = Machine default main storage pool is used for object. 0 1 — Bits 2-4 0) Transient storage pool selection = 0 Default main storage pool (process default or machine default as specified for main used for object. Transient storage pool is used for object. storage pool selection) = 1 Bit 6 is Block transfer on implicit access Bit 7 state modification = = 0 1 Transfer the minimum storage transfer size for this object. Transfer the machine default storage transfer size. - Unit — Reserved (binary This value This value number is 8 is 1 storage Bits 8-15 Reserved (binary Bits 16-31 0) Char(1) 0) Public authority Char(2) Extension offset Bin(4) Context System pointer Access group System pointer Note: The unit. storage units. instruction ignores the values associated with template entries annotated with an asterisk n. template extension must be specified for the initial owner specified creation option. Also, the temmust be specified ( extension offset must be nonzero) to specify any of the other template extension fields (those other than the initial owner user profile) as input to the instruction. A plate extension The template extension 16-byte aligned in is located by the extension offset the space. The following is field. The template extension must be the format of the template extension: System pointer • User » Largest size needed for space Bin(4) • Domain assigned Char(2) • profile to the object Hex 0000 The domain will be chosen by the machine. Hex 0001 The domain will be 'Common User'. Hex 8000 The domain will be 'Common System'. Reserved (binary Char(42) 0) permanent, it is owned by the user profile governing process execution. The assigned all private authority states for the object. The storage occupied by the created object is charged to this owning user profile. If the created object is temporary, there is no owning user profile, and all authority states are assigned as public. Storage occupied by the created context is charged to the creating process. If the created object owning user profile is is implicitly symbolic name that identifies the space within the machine. An by the machine. The object identification is used to identify the object on materialize instructions as well as to locate the object in a context that addresses the object. The object subtype must be hex EF. The object identification specifies the object type of hex 19 is implicitly supplied Chapter 6. Space Management Instructions 6-5 Create Space (CRTS) The existence attribute specifies whether the space is to be created as temporary or permanent. A temporary space, if not explicitly destroyed by the user, is implicitly destroyed by the machine when machine processing is terminated. A permanent space exists in the machine until it is explicitly destroyed by the user. The space whether the size of the space can vary. The space may have a fixed size allocation is as specified in the size of space field. The machine allocates a space of at least the size specified. The actual size allocated depends on an algorithm defined by a specific implementation. A fixed size space of zero length causes no space to be allocated. attribute specifies or a variable size. ^ the initial The initial context creation attribute field indicates that addressability is to be inserted into a context, must contain a system pointer that identifies a context where addressability to the newly created space is to be placed. If addressability is not to be inserted into a context, the context the context field is field ignored. fhe access group creation attribute field indicates that the space is to be created in an access group, must be a system pointer that identifies the access group in which the space is to be created. If the space is being created as a member of an access group, the existence attribute field must be temporary (bit 0 equals 0). If the space is not to be created into an access group, the access group field is ignored. If the access group field The public authority specified creation option controls whether or space is to be created with space is created with the public authority specified in the public authority field of the template. When no is specified, the public authority field is ignored and the space is created with default public authority. The default public authority depends on the value of the existence attribute An existence attribute value of temporary results in a default public authority of all authority; an existence attribute value of permanent results in a default public authority of no authority. Refer to the Grant Authority instruction for a description of the public authority field and a list of allowable values. the public authority specified in the template. When yes is not the specified, the The initial owner specified creation option controls whether or not the initial owner of the space is to be the user profile specified in the template. When yes is specified, initial ownership is assigned to the user profile specified in the user profile field of the template extension. When no is specified, initial ownership is assigned to the process user profile and the user profile field in the template extension is ignored. The initial owner user profile is implicitly assigned all authority states for the object. The storage occupied by the created space is charged to the initial owner. If yes is specified for this creation option when the existence attribute specifies temporary, a template value invalid (hex 3801) exception will be signaled. The set public authority in operand 1 creation option controls, when the public authority specified creation option has also been specified as yes, whether or not the public authority attribute for the space is to be set into the system pointer returned in operand 1. When yes is specified, the specified public authority is set into operand 1. When no is specified, public authority is not set into operand 1. When the public authority specified creation option is set to no, this option can not be specified as yes (or else a template value invalid (hex 3801) exception will be signalled) and the authority set into operand 1 is the default of no authority for a permanent or all authority for a temporary object (as specified by the existence attribute). The space creation option controls whether or not the space is to be initialized. When inieach byte of the space is initialized to a value specified by the initial value of space field. Additionally, when the space is extended in size, this byte value is also used to initialize the new allocation. When do not initialize is specified, the initial value of space field is ignored and the initial value of the bytes of the space are unpredictable. initialize tialize is specified, When do not initialize is specified for a space, internal machine algorithms do ensure that any storage resources last used for allocations to another object which are reused to satisfy allocations for the Chapter 6. Space Management Instructions 6-6 Create Space (CRTS) space are reset to a machine default value to avoid possible access of data which may have been stored in the other object. To the contrary, reusage of storage areas previously used by the space object are not reset, thereby exposing subsequent reallocations of those storage areas within the space to access of the data which was previously stored within them. The automatically extend space creation option controls whether the space is to be extended automatically by the machine or a space addressing (hex 0601) exception is to be signaled when a reference is made to an area beyond the allocated portion of the space. When yes is specified, the space will automatically be extended by an amount determined through internal machine algorithms. When no is specified, the exception will result. Note that an attempt to reference an area beyond that for the maximum size that a space can be allocated, will always result in the signaling of the space addressing (hex 0601) exception independently of the setting of this attribute. The automatically extend space creation option can only be specified when the space attribute has been specified as variable length. Invalid specification of the automatically extend space option results in the signaling of the template value invalid (hex 3801) exception. Usage of the automatically extend space function is limited. Predictable results will occur only when you ensure that the automatic extension of a space will not happen in conjunction with modification of the space size by another process. That is, you must ensure that when a process is using the space in a manner that could cause it to be automatically extended, it is the sole process which can cause the space size to be modified. Note that in addition to implicit modification through automatic extension, the space size can be explicitly modified through use of the Modify Space Attributes instruction. The hardware storage protection user state programs. three levels: It is level can be used to restrict access to the contents of the space by possible to limit the access of the space by user state programs into of 1 • Reference only (non-modifying storage references are allowed, modifying storing storage references yield a domain/protection violation (hex 4401) exception). • No storage references (all storage references, modifying or non-modifying yield a domain/protection violation (hex 4401) exception). • Full access (both modifying and non-modifying storage references are allowed). Process temporary space accounting can be used to detect when temporary space objects, created Temporary spaces that are created with the still exist at process termination time. process temporary space accounting field set to 0 will be “tracked” to the process which created them. Temporary spaces that are created with the process temporary space accounting field set to 1 will not be “tracked” to the creating process. within a process, At process termination time, any tracked spaces that exist may cause the machine to attempt to destroy the existing tracked spaces. If this is done, the destroy attempts would be performed as Ml program issued a Destroy Space (DESS) instruction for if an each of the existing spaces. The purpose of process temporary space accounting is to identify objects which may be “lost” in the system (until the next IPL). It should not intentionally be used (by Ml) as a method of cleaning up temporary space objects at process termination time. The machine does not guarantee that all spaces (that should be tracked) will indeed be tracked. Also, if the machine is attempting to destroy tracked spaces at process termination time, any failures in the deletion attempts (such as if a space is locked to another process) will be ignored (i.e. the space will not be destroyed) and no indication of this is presented to the Ml user. Process temporary space accounting only applies to temporary space objects. A value of 1 for the process temporary space accounting field when creating a permanent object will result in a template value invalid (hex 3801) exception. This is in spite of the fact that a value of 1 for this field would result in the same actions as when creating a permanent object (i.e. the object would not be tracked to the process). The exception is presented because this field is undefined for permanent objects. Chapter 6. Space Management Instructions 6-7 Create Space (CRTS) The ASP number field specifies the ASP number of the ASP on which the unit is to be allocated. A value of 0 indicates an ASP number is not specified and results in the default of allocating the object in the system ASP. Allocation on the system ASP can only be done implicitly by not specifying an ASP number. The only non-zero values allowed are 2 through 16 which specify the user ASP on which the space object will be allocated. The ASP number must specify an existing ASP or else an Auxiliary Storage Pool number invalid (hex 1C09) exception will be signaled. The ASP number field may only be specified for creation of a permanent object. The ASP number attribute of an object can be materialized, but cannot be modified. Invalid specification of the ASP number attribute results in the signaling of the template value invalid (hex 3801) exception. The performance class fields provide information allowing the machine to more effectively manage the space object considering the overall performance objectives of operations involving the space. The unit number field indicates the auxiliary storage unit on which the space should be located, if possible. The preferred unit number may not be specified in field which can be specified in the performance class field at object creation conjunction with specification of the ASP number attribute. The extension offset specifies the byte offset from the beginning of the operand 2 template to the beginning of the template extension. An offset value of zero specifies that the template extension is not provided. A negative offset value is invalid. A non-zero offset must be a multiple of 16 (to cause 16 byte alignment of the extension). Except for these restrictions, the offset value is not verified for correctness relative to the location of other portions of the create template. The largest size needed for space field of the template extension specifies, when nonzero, a value in bytes that indicates the largest size that will be needed for the space. This field is different from the size of space field which indicates the size for the initial allocation of the space. This field can be used communicate to the machine what the largest size needed for the space will be. Specification of a value larger than the maximum size space allowed for this object is invalid and results in signaling of the template value invalid (hex 3801) exception. Specification of a nonzero value that is less than the size of space field also results in the signaling of the template value invalid (hex 3801) exception. For to more information on the maximum allowed, see the Limitations topic at the end of the instruction's description. Specifying the largest size of space needed value allows the machine, under certain circumstances, to select usage of an internal storage allocation unit which best utilizes the internal addressing resources within the machine. Note that the internal storage allocation unit selected can alter the maximum modification size of the associated space for the object. However, the machine will always use an internal storage allocation unit that will allow for extension of the space to at least the value specified in the the largest size of space needed field. The maximum size to which the space can be modified is dependent upon specific implementations of the machine and can vary with different machine implementations. For more information on the affect of this option, see the Limitations topic at the end of this create instruction definition. The domain assigned field in the template extension allows the user of this domain for this object that would otherwise be chosen by the machine. Any value specified for the domain assigned field other than those instruction to override the listed will result in a template value invalid exception (hex 3801) being signalled. Chapter 6. Space Management Instructions 6-8 Create Space (CRTS) Limitations: The following are limits that The maximum size space allowed apply to the functions performed by this instruction. for this object Bytes. Note that the value specified in under any circumstances is limited to 16MB-256 needed field in the creation template largest size of space is used by the machine as part of the criteria used in selecting the appropriate internal storage allocation unit to be used for the storage allocations for the space. Authorization Required • - Insert — User — Context identified in owner operand 2 Retrieve — - profile of object Context referenced for address resolution Object control — Operand 1 if being replaced Lock Enforcement • Materialize — ° Contexts referenced for address resolution Modify — Context identified — User in operand profile of object — Access 2 owner group identified in operand 2 Exceptions Operands Exception 02 1 Access group X 02 object exceeds available space 06 Addressing X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X 01 08 space addressing violation Argument/parameter 01 0A parameter reference violation Authorization X 01 unauthorized for operation 0E Context operation X 01 duplicate object identification 10 Other 2 Damage encountered 04 system object damage X state Chapter 6, X Space Management X Instructions 6-9 Create Space (CRTS) Operands Exception 05 authority verification terminated due to 1 damaged X X X Machine-dependent exception 03 machine storage limit exceeded 04 object storage limit X exceeded X 09 auxiliary storage pool number invalid 20 22 X Machine support 02 machine check X 03 function check X Object access 01 object not found 24 X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X Pointer addressing invalid object 2E Resource control exceeded X Space management 01 38 X limit 01 user profile storage limit 36 X Lock state 01 invalid lock state 1C Other X 44 partial system object damage 1 2 object space extension/truncation X Template specification 01 template value invalid X Chapter 6. Space Management Instructions 6-10 Materialize Space Attributes (MATS) Materialize Op Code Space Operand (Hex) Operand 2 Space object 1 Receiver 0036 Operand 1: Space Operand 2: System — (MATS) Attributes pointer. pointer. ILE access MATS ( receiver var space_object : : space pointer ; system pointer ) The current Description: attributes of the the receiver specified by operand The template identified by materialization 8 is space object specified by operand operand 1 must be 16-byte aligned in the space. The format of the as follows: Char(8) Materialization size specification — Number — Number 2 are materialized into 1. of bytes provided for materialization Bin(4) of bytes available for materialization Bin{4) (always 96 for this instruction) 3 • Object identification Char(32) — Object type Char(1) — Object subtype Char(1) — Object name Char(30) Object creation options Char(4) — Bit 0 Bit 1 Existence attribute 0 1 = Temporary = Permanent — Space attribute 0 = Fixed-length 1 = Variable-length — Context 0 1 — = = Bit 2 Addressability not Addressability in in context context Access group 0 = 1 = Member Not Bit 3 member — Reserved (binary — Initialize 0 = of access group of access group Bits 4-12 0) space Bit 13 Initialize Chapter 6. Space Management Instructions 6-11 Materialize Space Attributes = Do 1 — not initialize Automatically extend space Bit 14 = No = Yes 0 1 — Hardware 00 01 10 11 — storage protection level Bits 15-16 = Reference and modify allowed for user state programs = Only reference allowed for user state programs = Invalid (undefined) = No reference or modify allowed for user state programs Reserved (binary Reserved (binary Bits 17-31 0) Char(2) 0) ASP number Char(2) Size of space Bin(4) Initial value of space Char(1) Performance class Char(4) - Space Bit 0 = alignment The space associated with the object 16-byte alignments within the space. 1 — Main 1 — is If allocated to allow proper alignment of pointers at no space (binary 0) Bits 1-4 storage pool selection Bit 5 = Process default main storage pool is used for object. = Machine default main storage pool is used for object. Transient storage pool selection 0 = = — Bit 6 Default main storage pool (process default or machine default as specified for main storage pool selection) 1 Transient storage pool is is used for object. used for object. Block transfer on implicit access state modification 0 1 — 0 is specified for the object, this value must be specified for the performance class. = The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space as well as to allow proper alignment of input/output buffers at 512-byte alignments within the space. - Reserved 0 = Unit Bit 7 minimum storage transfer size for this object. This value is 1 storage Transfer the machine default storage transfer size. This value is 8 storage units. Transfer the number - Reserved Bits 16-31 Char(7) 0) Context System pointer Access group System pointer The first unit. Bits 8-15 (binary 0) Reserved (binary tion. (MATS) 4 bytes that are materialized identify the total number of bytes provided for use by the instrucis supplied as input to the instruction and is not modified by the instruction. A value This value of less than 8 causes a materialization length (hex 3803) exception. The second 4 bytes that are materialized identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. Chapter 6. Space Management Instructions 6-12 Materialize Space Attributes (MATS) the byte area identified by the receiver If is greater than that required to contain the information No exceptions (other than the materialization length the event that the receiver contains insufficient area for requested, then the excess bytes are unchanged. exception described previously) are signaled the materialization. See the Create Space in instruction for a description of these fields. This instruction cannot be used to materialize the public authority specified creation option, the initial owner specified creation option, the process temporary space accounting creation option, or the template extension which can be specified on space creation. The Materialize Authority instruction can be used to materialize the current public authority for the space. The Materialize System Object instruccan be used to materialize the current owner of the space. tion Authorization Required • Operational or space authority — Operand • 2 Retrieve — Contexts referenced for address resolution Lock Enforcement ° Materialize — Operand — Contexts 2 referenced for address resolution Exceptions Operands Exception 06 X X X X 03 range X X 06 optimized addressability invalid X X X X space addressing violation parameter reference violation Authorization X 01 unauthorized for operation 10 Damage encountered 04 system object damage 44 partial X state 05 authority verification terminated due to 1 damaged X X X object system object damage X X X Lock state X 01 invalid lock state 1C Other Argument/parameter 01 0A 2 02 boundary alignment 01 08 1 Addressing Machine-dependent exception 03 machine storage limit exceeded X Chapter 6. Space Management Instructions 6-13 Materialize Space Attributes (MATS) Operands Exception 20 Machine support 22 24 1 X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification does not exist 02 pointer type invalid X X X X 03 pointer addressing invalid object Resource control exceeded X Space management 01 38 X limit 01 user profile storage limit 36 Other 02 machine check 01 pointer 2E 2 space extension/truncation X Template specification 03 materialization length exception X Chapter 6. Space Management Instructions 6-14 Modify Space Attributes (MODS) Modify Space Attributes (MODS) Op Code Operand 1 System object. (Hex) 0062 Operand 2 Size or Space modification template. Operand 1: System Operand 2: Binary scalar or character(28) scalar (fixed length). — pointer. ILE access M0DS1 ( var space_object var size : : system pointer ; signed binary ) OR M0DS2 ( var system_object var space_modification_template : : system pointer ; aggregate ) Description: The attributes of the space associated with the system object specified for operand 1 are in operand 2. Operand 1 may address any system object. modified with the attribute values specified The operand 2 space modification template is specified with one of two formats. The abbreviated format, operand 2 specified as a binary scalar, only provides for modifying the size of space attribute. The full format, operand 2 specified as a character scalar, provides for modifying the full set of space attributes. When operand a binary value, specifies the size bytes to which the space size is to be modiextended or truncated accordingly to match as closely as possible the specified size. The modified space size will be of at least the size specified. The actual size allocated is dependent upon the algorithm used within the specific implementation of the machine If the space is of fixed size, or if the value of operand 2 is negative, or if the operand 2 size is larger than that for the largest space that can be associated with the object, the space extension/truncation exception is signaled. When operand 2 is a character scalar, it specifies a selection of space attribute values to be used to modify the attributes of the space. It must be at least 28 bytes long and have the fied. 2 The current is allocation of the it space in is following format: • Modification selection Char{4) — Bit 0 Bit 1 Modify space length attribute 0 1 — = No = Yes Modify size of space 0 1 = No = Yes Modify 0 1 initial value of space Bit 2 = No = Yes Chapter 6. Space Management Instructions 6-15 Modify Space Attributes (MODS) — Modify performance class 0 1 - 1 — initialize 1 space Bit 4 attribute = No = Yes Reinitialize 0 - = No = Yes Modify 0 Bit 3 space Bit 5 = No = Yes Modify automatically extend space Bit 6 attribute 0 1 — Create secondary associated space 0 1 — = No = Yes Bit 7 = No = Yes Reserved (binary Bits 8-31 0) Indicator attributes — Reserved (binary — Space length 0 1 — 1 Bit 1 space Bit 2 = Initialize = Do not initialize Bit 3 = No = Yes Reserved (binary Bits 4-14 0) — Hardware storage protection level* 00 = Reference and modify allowed for user state programs 01 = Only reference allowed for user state programs 10 = Invalid (undefined) 11 = No reference or modify allowed for user state programs — Reserved (binary 0) Maximum size of space* Bits 15-16 Bits 17-31 Bin(4) Size of space Initial 1 Fixed length Automatically extend space 0 — Bit 0 0) Variable length Initialize 0 — = = Char(4) Bin(4) value of space Char(1) Performance class Char(4) Reserved (binary 0) Char(1) Secondary associated space number UBin(2) Reserved (binary Char(4) 0) Chapter 6. Space Management Instructions 6-16 Modify Space Attributes (MODS) * These fields will be ignored when create secondary associated space The modification selection indicator The modify space length is 0. be performed on the space. fields select the modifications to whether or not the space length is used to no is specified, When the space attribute modification selection field controls When yes specified, the value of the space length indicator is is to be modified. modify the space to be specified fixed or variable length attribute. length indicator attribute value is ignored and the space length attribute attribute is not modified. The modify size of space modification selection field controls whether or not the allocation size of the space is to be modified. When yes is specified, the current allocation of the space is extended or truncated accordingly to match as closely as possible the specified size in the size of space field. The modified size will be at least the size specified. The actual size allocated is dependent upon the algorithm used within the specific implementation of the machine. cation of the space is not modified and the size of space field When no is is specified, the current allo- ignored. Modification of the size of space attribute for a space of fixed length can only be performed tion with modification of the modified to the same space length attribute. In this case, the space length attribute fixed length attribute or to the variable length attribute. An attempt in conjunc- may be to modify the space of fixed length without modification of the space length attribute results in the signaling of the space extension/truncation (hex 3601) exception. Modification of the size of space attribute for a space of variable length can always be performed separately from a modification of the space length attribute. size of space attribute for a When the size of space attribute is if the value of the size of space field is negative or space that can be associated with the object, the space to be modified, specifies a size larger than that for the largest extension/truncation (hex 3601) exception is signaled. initial value of space modification selection field controls whether or not the initial value of space attribute is to be modified. When yes is specified, the value of the Initial value of space field is used to modify the corresponding attribute of this space. This byte value will be used to initialize any new space allocations for this space due to an extension to the size of space attribute on the current execution of this instruction as well as any subsequent modifications. When no is specified, the initial value of space field is ignored and the initial value of space attribute is not modified. The modify field controls whether or not the performance be modified with the values relating to space objects. When yes is specified, the value of the performance class field is used to modify the corresponding attribute of the specified system object. When no is specified, the performance class attribute of the specified system object is not modified. The modify performance class modification selection class attribute of the specified system object is to The modify initialize space attribute modification selection field controls whether or not the initialize space attribute is to be modified. When yes is specified, the value of the initialize space indicator attribute is used to modify that attribute of the specified space to the specified value. When no is specified, the initialize space indicator attribute value is ignored and the initialize space attribute is not modified. Changing the value of the initialize space attribute only affects whether or not future extensions of the space will be initialized or not. That is, it is the state of this attribute at the time of allocation of the storage for a space that determines whether that newly allocated storage area will be initialized to the initial value specified for the space. Modifications of this attribute subsequent to the allocation of storage to a space have no effect on the value of that previously allocated storage area. space modification selection field controls whether the storage allocated to the space is to be reinitialized in its entirety. When no is specified, the space is not reinitialized. When yes is specified, the space is reinitialized. This re-initialization is performed after all other attribute modifications which may also have been specified on the instruction have been made. Thus changes to the size of The reinitialize Chapter 6. Space Management Instructions 6-17 Modify Space Attributes (MODS) the space, the initial value of the space, etc. will be put into effect and be considered the current attributes of the space for purposes of the re-initialization. The byte value used for the re-initialization is either the current initial value for the space if the initialize space attribute for the space currently specifies yes, or a value of hex 00 if Note that specifying yes for the the initialize space attribute currently specifies no. space modification selection field for a space with current no operation, because such a space has no allocated storage to reinitialize. Also, note that re-initialization of a space will have the side effect of resetting partial damage for a space object containing the space if the space object had previously been marked as having partial damage. This only applies to space objects; i.e. re-initialization of an associated space does not have the side effect of resetting partial damage for the Ml object containing it. reinitialize attributes of fixed length size zero results The modify automatically extend space automatically extend space attribute ically attribute modification selection field controls to be modified. is extend space indicator attribute in When used to modify that yes is whether or not the specified, the value of the automat- attribute of the specified space to the space indicator attribute value is ignored and the automatically extend space attribute is not modified. The automatically extend space attribute can only be specified as yes when the space length attribute for the space is already variable length, or when the space length attribute is being modified to variable length. Invalid specification of the automatically extend space attribute results in the signaling of the invalid space modification (hex 3602) specified value. When no is is specified, the autmatically extend exception. Modification to or from the state of a space being fixed length of size zero can not be performed for the following objects: Class of service description Controller description Cursor Data space Logical unit description Mode description Network description Space Program (when attempted while If is such a modification is attempted user state on a security level 40 or higher system). in for these objects, the invalid space modification (hex 3602) exception signaled. Specifying yes for the modify performance class modification selection field is only allowed when the space to be modified is a fixed length space of size zero. This modification may be specified in conjunction with other modifications. Only bit 0 of the performance class field is used to modify the performance class attribute of the specified system object. A bit value of zero requests that the start of the space storage provide 16-byte multiple (pointer) machine address alignment. A bit value of one requests that the start of the space storage provide 512-byte multiple (buffer) machine address alignment. Bits 1 through 31 are ignored. Specifying yes for the modify performance class modification selection field when the space to be modified is not a fixed length space of size zero results in the signaling of the invalid space modification (hex 3602) exception. The cre ate secondary associated space for the object. All field indicates if a secondary associated space is to be created the indicator attributes and size and value fields are used for this create. The secondary associated space to be created is indicated by the secondary associated space number field. the specified space already exists, the invalid space modification (hex 3602) exception is signalled. When this bit is set to yes, all other modification selection bits If are ignored. Chapter 6. Space Management Instructions 6-18 Modify Space Attributes (MODS) Specifying the largest size of space needed value allows the machine, under certain circumstances, to select usage of an internal storage allocation unit which best utilizes the internal addressing resources ; within the machine. Note that the internal storage allocation unit selected can alter the maximum mod- ; ification size of the associated space for the object. However, the machine storage allocation unit that will allow for extension of the space to at least will always use an internal the value specified in the | The maximum size to which the space can be modified is implementations of the machine and can vary with different machine imple- the largest size of space needed | dependent upon specific field. | mentations. | | used to indicate which secondary space is to be primary associated space of the space object is moditied. If this field is not zero and no secondary associated spaces are allowed for the object, the scalar value invalid (hex 3203) exception will be signalled. The secondary associated space number created or modified. | | When field is this field is zero, the | A fixed length space of size zero is defined by the machine to have no internal storage allocation. Due is, in essence, the same as a destroy or create for the space to this, a modification to or from this state | | associated with the specified system object. The effect of modifying to this state is similar to destroying the associated space in that address references to the space through previously set pointers will result in signaling of the object destroyed exception. When a primary associated space is destroyed by using this method, any secondary associated spaces for the object are also destroyed. Additionally, an attempt to set a space pointer to the space associated with the specified system object through the Set Space Pointer from Pointer instruction will result in the signaling of the invalid space reference (hex 0605) exception. To the contrary, modifying the space attributes from this state is similar to creating an associated space in that the Set Space Pointer from Pointer instruction can be used to set a space pointer to the start of a storage within the associated space and the allocated space storage can be used to contain space data. space is always by an implementation-defined multiple of 256 bytes. This means that if, for example, the implementation defined multiple is 2 (or 512 bytes), any modification of the space size will be in increments of 512 bytes. The extension and truncation of a Authorization Required • Object management — Operand • 1 Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize » Contexts referenced for address resolution Object control - Operand • 1 (when operand 2 is binary) 1 (when operand 2 Modify — Operand is character) Events 0002 Authorization 0101 Object authorization violation 000C Machine resource Chapter 6. Space Management Instructions 6-19 Modify Space Attributes (MODS) 0201 Machine auxiliary storage threshold exceeded 0202 User auxiliary storage pool threshold exceeded 0203 User auxiliary storage pool overflow 0204 Asp unprotected space overflow 0501 Machine address threshold exceeded 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor 0801 Process storage time exceeded limit exceeded 0016 Machine observation 0101 Instruction reference 0017 Damage set 0401 System object damage set damage 0801 Partial system object set Exceptions Operands Exception 06 1 2 01 space addressing violation X X 02 boundary alignment X X 03 range X X 05 invalid space reference X 06 optimized addressability invalid 08 parameter reference violation X X X Authorization 01 unauthorized for operation 10 X Argument/parameter 01 0A X Damage encountered 04 system object damage state X X 05 authority verification terminated due to damaged object 44 1 partial X X X Lock state X Machine-dependent exception 03 machine storage 04 object storage 20 X X system object damage 01 invalid lock state 1C Other Addressing limit limit exceeded X exceeded X Machine support 02 machine check X 03 function check X Chapter 6. Space Management Instructions 6-20 Modify Space Attributes (MODS) Operands 1 2 01 object not found X X 02 object destroyed X X 03 object suspended X X Exception 22 24 Object access 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification X X 02 pointer type invalid X X 03 pointer addressing invalid object X 01 pointer 2A does not exist Program creation 06 invalid operand type X X 07 invalid operand attribute X X 08 invalid operand value range X X invalid operand length 0C invalid operand odt reference bits Resource control are not zero X X X X X exceeded Scalar Specification X 03 scalar value invalid 36 X limit 01 user profile storage limit 32 X 0A 0D reserved 2E Other Space management 01 space extension/truncation X X 02 invalid space modification X X Chapter 6. Space Management Instructions 6-21 Heap Management Chapter 7. Heap Management Instructions Instructions I | This chapter describes the instructions used for heap management. These instructions are in alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction [ Summary.” | Heap Space Storage (ALCHSS) Create Heap Space (CRTHS) Destroy Heap Space (DESHS) Free Heap Space Storage (FREHSS) Free Heap Space Storage From Mark (FREHSSMK) Materialize Heap Space Attributes (MATHSAT) Reallocate Heap Space Storage (REALCHSS) Set Heap Space Storage Mark (SETHSSMK) Allocate © Copyright IBM Corp. 1991, 1993 7-3 7-6 7-11 7-13 7-15 7-17 7-22 7-25 7-1 Heap Management Instructions I j i Chapter 7. Heap Management Instructions 7~2 Allocate Allocate Heap Space Storage (ALCHSS) Heap Space Storage (ALCHSS) I Op Code 03B3 j Operand 2 Heap Identifier Operand 1 Space allocation (Hex) | Operand 3 Size of space allocation Operand 1\ Space Operand 2: Binary(4) scalar or Operand 3: Binary(4) scalar. — pointer. — ILE access ALCHSS ( heapjdenti tier : : ) signed binary ; signed binary location space pointer /* space_allocation */ si z e_°f_ s pace_al Description: | null. : A heap space storage allocation of at least the size indicated by operand 3 is provided set to address the first from the heap space indicated by operand 2. The operand 1 space pointer is boundary speciminimum the as great as least at boundary byte of the allocation which will begin on a tied when the heap space was created. I | | addressable bytes. Each allocation associated with a heap space provides a continuum of contiguously The contents other. each with affinity addressability no have Individual allocations within a heap space specified was allocations heap of initialization unless of the heap space allocation are unpredictable | | | when the heap space was created. j Simultaneous operations against a heap space from multiple processes produce unpredictable results. | is may not supported and | allocation The maximum single allocation allowed is determined by the maximum single 16M-64K possible is allocation single maximum The when the heap space was created. | size specified bytes. | of heap space storage the responsibility of the using program to see that only the amount bounds of the requested space will the outside storage space heap to Reference requested is used. to the Free Heap Space supplied be must returned address exact The unpredictable results. It | | is produce | Space Storage (FREHSS) instruction when the user has completed use of the heap space storage. | A | default heap space (heap value of identifier 0) is automatically available in each activation group space without issuing a Create Heap Space (CRTHS) instruction. The default heap operand When space. heap default the against first Allocate Heap Space is issued | is 2 created is null, when the the default | heap space (heap | identifier of 0) The machine supplied | provides the allocation. attributes of the default ° Maximum » Minimum boundary requirement • The creation size advisory single allocation size 16M is - heap space are as 64K follows: bytes. | a 16 byte boundary. is | is 4KB unless the size of the allocation request dictates a larger cre- | ation size be used. | • The extension size advisory is 4KB unless the size of the allocation request dictates a larger exten- | sion size be used. Chapter 7. Heap Management Instructions 7-3 Allocate • Domain • Normal allocation strategy. • A heap space mark | | | is Heap Space Storage (ALCHSS) determined from the state of the program issuing the instruction. The transfer size not allowed. is is 1 storage unit. The process access group membership advisory value is taken from the activation group. Default ac 'vation groups get this value from the attribute specified on the Initiate Process (INITPR) instruction. Other activation groups get Program (CRTBPGM) Heap space storage Neither operand 2 nor 3 L I | I 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 I I I time exceeded exceeded 0402 Hardware storage violation 0017 Damage set 0401 System object damage set 0801 Partial system object damage set | I I limit 0016 Machine observation 0101 Instruction reference 0401 Domain violation I | Maximum processor 0801 Process storage I | modified by the instruction. is 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded | | allocations are not overwritten to the freed value after being freed. Events I | value from the attribute specified on the Create Bound program which initiated the activation group. allocations are not initialized to the allocation value. Heap space storage | this instruction for the Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 10 2 3 X X X X Other X X X X X X X X X X X Argument/parameter 01 | 1 Addressing parameter reference violation x Damage encountered Chapter 7. Heap Management Instructions 7-4 Allocate Heap Space Storage (ALCHSS) Operands Exception 04 system object damage state 05 authority verification terminated due to 44 1C partial damaged 1 2 3 Other X X X X X object X system object damage X X Machine-dependent exception X 03 machine storage limit exceeded 20 24 Machine support 02 machine check X 03 function check X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X X X X X X X X 03 Pointer addressing invalid object 44 Domain 01 45 X specification Domain Heap X Violation specification 01 Invalid Heap 03 Heap Space X Identifier X Full X 04 Invalid Size Request X 05 Heap Space Destroyed X 06 Invalid Heap Condition Chapter 7. X X Heap Management X Instructions 7-5 Create Heap Space (ORTHS) I | ! Create Heap Space (CRTHS) Op Code (Hex) Operand 1 Heap Identifier 03B2 Operand 2 Heap Space | Operand 1: | Operand 2: Binary(4) variable scalar Space pointer — ILE access 1 | ! heap space The heap is | identifier used The following f Materialize Heap Space is Reserved (binary • Maximum » Minimum boundary requirement • Creation size • Extension size • Domain/Storage protection | | Hex 0000 Hex 0001 Hex 8000 • Mark Attributes (MATHSAT) 2 instructions. must be 16-byte aligned 0) 1 = = UBin(4) UBin(4) UBin(4) Bin(2) = System should chose the Domain = The heap space domain should be "Common = The heap space domain should be "Common User" System" creation options Char(6) Bit 0 Normal allocation strategy Force process space creation on each allocate — Heap Space Mark 0 = Allow heap space mark 1 = Prevent heap space mark — Block transfer 0 = the space, UBin(4) Allocation strategy 0 in Char(8) single allocation Heap space — in the heap space creation template perform allocations and marks against the the format of the heap space creation template: • | to operand 1 represents the heap space. This identifier is used for the Storage (ALCHSS), Destroy Heap Space (DESHS), Set Heap Space Storage The heap space creation template identified by operand Operand 2 is not modified by the instruction. | [ created with the attributes supplied 2. identifier returned in f (SETHSSMK) and i is The heap space returned in operand 1. Spac | signed binary, space pointer : : A heap space Description: specified by operand | — CRTHS ( var heapjdentifier creation_templ ate | | creation template I Transfer the This value minimum storage is 1 storage Bit 1 Bit 2 transfer size. unit. Chapter 7. Heap Management Instructions 7-6 Create Heap Space (ORTHS) 1 — 1 = Do not = Create member create the heap space the heap space in Bit 3 in the PAG. the PAG. Bit 4 Allocation initialization 0 1 — Transfer the machine default storage transfer size. This value is 8 storage units. Process access group 0 - = = Do not initialize allocations. = Initialize allocations. Bit 5 Overwrite freed allocations 0 1 = Do not overwrite freed allocations. = Overwrite freed allocations. - Reserved Bits 6-7 (binary 0) — Allocation value Char(1) - Freed value Char(1) — Reserved (binary Reserved (binary Char(3) 0) Char(64) 0) The maximum single allocation of any single allocation from the heap space is useful for controlling the use of the heap space and may also improve performance for some cases when the machine can optimize access based on this attribute. The minimum value that can be specified is 4 bytes, and the maximum value that can be specified is 16M-64K bytes. If zero is specified, the default value of 16M-64K bytes will be used. Values outside the range indicated will cause a template value invalid (hex 3801) exception. The minimum boundary alignment associated with any allocation from the heap space can be specified alignment. The in the template. The minimum value that can be specified is a 4 byte boundary alignment. If zero is speciboundary 512 byte specified is a maximum boundary alignment that can be be rounded alignment will boundary minimum fied, a default of a 16 byte boundary will be used. The (hex 3801) invalid template value up to a power of 2. Values outside the range indicated will cause a exception. The creation size of the heap space can be specified in the template. If zero is specified the system maximum will compute a default value. The minimum value that can be specified is 512 bytes. The unit storage rounded up to a value that can be specified is 16M-1K bytes. The value specified will be exception. boundary. Values outside the range indicated will cause a template value invalid (hex 3801) This is an advisory value only. The machine may decide to override the value specified based on system resource constraints. The extension size of the heap space can be specified in the template. If zero is specified the system maximum will compute a default value. The minimum value that can be specified is 512 bytes. The value that can be specified is 16M-1K bytes. The value specified will be rounded up to a storage unit boundary. Values outside the range indicated will cause a template value invalid (hex 3801) exception. This is an advisory value only. The machine may decide to override the value specified based on system resource constraints. The domain/storaqe protection field in the template allows the user of this instruction to override the domain for the heap space that would otherwise be chosen by the machine. The domain/storage protection attribute can be used to restrict access to the contents of the heap space by user state programs. It is possible to limit the access of the heap space by user state programs into 1 of two levels: Chapter 7. Heap Management Instructions 7-7 Create Heap Space (CRTHS) • No storage references (all storage references, modifying or non-modifying yield a domain/protection violation (hex 4401) exception). This is Common System. Full access (both modifying and non-modifying storage references are allowed). This is User. Common Only a system state process can specify a heap space to be created with a domain of Common System. If a user state program attempts to specify the domain/storage protection as Common System a template value invalid (hex 3801) exception will be signaled. Any value other than the ones listed will cause a template value invalid (hex 3801) exception to be signaled. , | M J The rmal allocation strategy as defined by the machine will be used unless the force process space creation on each allocation attribute is indicated. This option should only ations, such as when necessary for ; I | | I | allocation. be used in unusual situdebug of application problems caused by references outside an The h eap space mark attribute can be used to prevent the use of the Set Heap Space Storage Mark (SETHSSMK) and Free Heap Space Storage from Mark (FREHSSMK) instructions on a heap space. llock transfer on a heap space is used to increase the performance of a heap space based on knowledge of the program creating the heap space on how that heap space will be used. This bute is used only when the heap space is not a member of a process access group (PAG). prior attri- A heap space can be j i j I ! | | | I | | | | | | | created as a process access group (PAG) member of the currently executing specified by the fircoes s access group member It is possible for the PAG to overflow at which point any requested heap space creations or extensions will not reside in the PAG Thus the specification to have the heap space as a member of the PAG is only an advisory which the machine may decide to override. process, if The all ocation initialization field in the template allows the user of this instruction to specify that all storage allocations from the heap space being created will be initialized to the allocation value supplied in the template. If the user chooses not to initialize heap space storage allocations the initial value of heap space storage allocations is unpredictable but will not expose data produced by a different user profile. The Ov erwrite freed allocations field in the template allows the user of this instruction to specify that all heap space storage allocations upon being freed will be overwritten with the the freed value supplied in the template. If the user chooses not to overwrite heap space storage allocations when contents of the freed allocations freed the will be unaltered. A default heap space (heap identifier value of 0) is automatically available in each activation group without issuing a Create Heap Space (CRTHS) instruction. The default heap space is created on the irst allocation request of the default heap space. See Allocate Heap Space Storage (ALCHSS) for a description of the default heap space. A heap space is scoped to an activation group, thus the maximum life of a heap space is the life of the activation group in which the heap space was created. A heap space can only be destroyed from within the activation group in which it was created. Simultaneous operations against a heap space from multiple processes produce unpredictable results. Chapter 7. is not supported and Heap Management may Instructions 7-8 Create Heap Space (CRTHS) The following are Limitations: limits that apply to the functions performed by this instruction. | The amount of heap space storage that can be allocated for a single heap space is 4G-512K bytes. Due to fragmentation a heap space may grow to 4GB-512KB without having 4GB-512KB of outstanding heap space storage allocations. | | | The maximum allocation size of any single allocation from the heap space is limited to 16MB-64K | bytes. A smaller maximum allocation size can be specified. | Events | 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded | | | 000 D Machine status | 0101 Machine check | 0401 Auxiliary storage device requires service | 0010 Process 0701 Maximum processor time exceeded 0801 Process storage limit exceeded | | | 0016 Machine observation 0101 Instruction reference | | Domain violation 0402 Hardware storage 0401 | violation | 0017 Damage set | 0401 System object | damage set damage 0801 Partial system object set | Exceptions | Operands 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception Other | 06 Addressing | 01 space addressing violation | | | | 08 Argument/parameter | 01 parameter reference violation | 10 XXX XXX Damage encountered | 04 system object damage state | 05 authority verification terminated due to damaged X object | 44 partial system object damage | 1C Machine-dependent exception | X 03 machine storage limit exceeded 04 object storage limit X exceeded | Chapter 7. Heap Management Instructions 7-9 Create Heap Space (ORTHS) Operands Exception 20 Machine support 1 2 02 machine check X 03 function check 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X 03 Pointer addressing invalid object 38 X Template specification 01 template value invalid 44 Other Domain 01 X specification Domain Violation X Chapter 7. Heap Management X Instructions 7-10 Destroy Heap Space (DESHS) Destroy Heap Space (DESHS) I | Op Code Operand 1 Heap Identifier (Hex) 03B1 j Operand Binary{4) variable scalar. 1\ | DESHS ( var heapj identifier : signed binary ) This instruction destroys and removes from the current activation group the heap space specified by the heap identifier in operand 1. Subsequent use of this heap identifier within the activation group will result in an invalid identifier (hex 4501) exception. The heap identifier was returned Description: on the Create Heap Space (CRTHS) instruction. An attempt to destroy the default heap space (heap identifier value of 0) will result in an invalid request (hex 4502) exception. Space pointer references to heap space allocations from a destroyed heap space will cause unpredictable results. All heap spaces are implicitly destroyed when the activation group in which they were created is destroyed. Operand 1 is not modified by the instruction. Events 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor time exceeded 0801 Process storage limit exceeded 0016 Machine observation 0101 Instruction reference 0401 Domain violation 0402 Hardware storage violation 0017 Damage set damage set system object damage 0401 System object 0801 Partial set Exceptions Operands 1 Exception Chapter 7. Heap Management Other Instructions 7-1 Destroy Heap Space (DESHS) Operands | | Exception 06 Addressing 01 | X | 03 range X 06 optimized addressability invalid X 08 10 parameter reference violation damage 44 | 1C 20 02 machine check | 03 function check X Pointer specification does not 02 pointer type invalid Domain 01 | 45 X X | 44 X Machine support 01 pointer | X Machine-dependent exception | 24 X X system object damage partial | | X 03 machine storage limit exceeded | | state 05 authority verification terminated due to damaged object | | X Damage encountered 04 system object I | Argument/parameter 01 I | X 02 boundary alignment | | space addressing violation | | Other 1 X X specification Domain Heap exist Violation X specification 01 Invalid Heap Identifier | 02 Invalid Request | 05 Heap Space Destroyed | 06 Invalid Heap Condition X X X X Chapter 7. Heap Management X Instructions 7-12 Free Heap Space Storage (FREHSS) Free Heap Space Storage (FREHSS) I | Op Code Operand 1 Space allocation (Hex) 03B5 j Operand Space 1\ pointer. | — ILE access FREHSS ( space_al location : space pointer ) The heap space storage allocation beginning Description: at the byte allocated from the heap space which supplied the allocation. addressed by operand De-allocation 1 makes the storage is de- avail- able for reuse by subsequent Allocate Heap Space Storage (ALCHSS) instructions. The entire space allocation is de-allocated; partial de-allocation is not supported. A free of heap space storage can be performed without regard to the activation group in which it was allocated, as long as the allocation was done by the same process. Operand 1 must be exactly equal to the space pointer that was returned by some previous Allocate Heap Space Storage (ALCHSS) or Reallocate Heap Space Storage (REALCHSS) instruction. If it is not, an invalid request (hex 4502) exception will be signaled. Subsequent references to space allocations which have been freed cause unpredictable FREHSS will signal a domain violation (hex 4401) exception de-allocate heap space storage Operand 1 is in if a results. program running user state attempts a heap space with a domain of Common to System. not modified by the instruction. Events 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded 000 D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor 0801 Process storage time exceeded limit exceeded 0016 Machine observation 0101 Instruction reference Domain violation 0402 Hardware storage 0401 0017 Damage violation set 0401 System object damage set damage 0801 Partial system object set Chapter 7. Heap Management Instructions 7-13 Free Heap Space Storage (FREHSS) | Exceptions Operands Exception Other 1 06 Addressing 01 08 X 03 range X 06 optimized addressability invalid X Argument/parameter parameter reference violation damage state 05 authority verification terminated due to 44 partial X damaged object X X Machine-dependent exception limit exceeded X Machine support 02 machine check X 03 function check 24 X X system object damage 03 machine storage 20 X Damage encountered 04 system object 1C X 02 boundary alignment 01 10 space addressing violation X Pointer specification 01 pointer does not exist X 02 pointer type invalid X 03 Pointer addressing invalid object 44 Domain 01 45 specification Domain Heap Violation X specification 02 Invalid Request X 05 Heap Space Destroyed X 06 Invalid Heap Condition X Chapter 7. Heap Management X Instructions 7-14 Free Heap Space Storage From Mark (FREHSSMK) Free Heap Space Storage From Mark Op Code Operand 1 Mark Identifier (Hex) 03B9 Operand — Space pointer data 1: (FREHSSMK) object. ILE access FREHSSMK ( var mark_identifier : space pointer ) All heap space allocations which have occurred from the heap space since it was marked, with the mark identifier supplied in operand 1, are freed. This may include heap space storage marked by intervening Set Heap Space Storage Mark (SETHSSMK) instructions. The mark identifier specified in operand 1 and all mark identifiers obtained since the heap space was marked by operand 1 are cleared from the heap space. An attempt to free heap space storage from a mark that has already been cleared by a previous FREHSSMK instruction will result in an invalid identifier (hex 4507) exception. A free of heap space storage can be performed without regard to the activation group Description: in which it was FREHSSMK will attempts a free Operand 1 is allocated, as long as the allocation was done by the same process. domain violation (hex 4401) exception if a program running user state heap space storage from mark for a heap space with a domain of Common System. signal a not modified by the instruction. Events 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor 0801 Process storage time exceeded limit exceeded 0016 Machine observation 0101 Instruction reference 0401 Domain violation 0402 Hardware storage violation 0017 Damage set 0401 System object damage set damage 0801 Partial system object set Exceptions Operands Exception 1 Chapter 7. Heap Management Other Instructions 7-15 Free Heap Space Storage From Mark (FREHSSMK) Operands 51 CtllUD 1 1 Exception 06 Addressing 01 1 X 1 03 range X 1 06 optimized addressability invalid X 1 Argument/parameter 1 01 10 parameter reference violation damage state X 05 authority verification terminated due to damaged object 1 44 1 1C partial X X system object damage X X Machine-dependent exception 1 03 machine storage 1 04 object storage limit limit exceeded X exceeded 09 auxiliary storage pool number invalid 1 20 1 Machine support 1 02 machine check X 1 03 function check X 1 24 Pointer specification does not 1 01 pointer 1 02 pointer type invalid exist X X 03 Pointer addressing invalid object 1 44 Domain 01 1 1 X Damage encountered 04 system object 1 1 X 02 boundary alignment 1 J space addressing violation 1 08 Other 1 45 specification Domain Heap Violation X specification 1 02 Invalid Request 1 05 Heap Space Destroyed 1 06 Invalid Heap Condition X ! 07 Invalid Mark Identifier X X X Chapter 7. Heap Management X Instructions 7-16 Materialize Materialize Heap Space Attributes Heap Space Attributes (MATHSAT) (MATHSAT) I Op Code Materialize tem- Operand 2 Heap identifier plate template Operand (Hex) 03B7 1 Operand 1 : Space pointer. Operand 2: Space pointer. Operand 3: Character(l) scalar (fixed length). MATHSAT ( materialize_template heap_i denti f i er_templ ate var attribute selection This instruction Description: specified by Operand 3 operand 2 will Operand 3 Attribute Selection space pointer space pointer aggregate materialize the information selected by operand 3 for the heap space and return the selected information in the template indicated by operand can have three possible values: » Hex 00 - Return heap space attributes 9 Hex 01 - Return heap space attributes and mark information. 9 Hex 02 - Return heap space attributes, mark information and allocation information. Any value 1. for operand The heap space 3 other than those listed will attributes template identified by cause a scalar value invalid (3203) exception. operand 1 must be 16-byte aligned in the space. If operand 3 is equal to hex 00, then only the heap space attributes template information is returned. The format of the attributes template information is as follows (see the Create Heap Space instruction for a description of • these fields): Template size specification Char(8) - Number — Number of bytes provided for materialization Bin(4) of bytes available for materialization Bin(4) • Maximum 9 Minimum boundary requirement UBin(4) » Creation size UBin(4) • Extension size UBin(4) • Domain Bin(2) Hex 0001 Hex 8000 « UBin(4) single allocation = = The heap space domain The heap space domain is is "Common User" "Common System" Heap space creation options Char(6) — Bit Allocation strategy 0 1 = Normal allocation strategy = Force implicit space creation 0 on each allocate Chapter 7. Heap Management Instructions 7-17 Materialize Heap Space Attributes (MATHSAT) - Heap Space Mark 0 1 - = = Bit Allow heap space mark Prevent heap space mark Block transfer 0 = Bit 2 = minimum storage Transfer the This value 1 1 storage is 1 transfer size. unit. Transfer the machine default storage transfer size. is 8 storage units. This value - Process access group 0 1 - create the heap space the heap space in Bit 3 in the PAG. the PAG. Initialization allocations 0 1 - = Do not = Create member Bit 4 = Do not initialize allocations. = Initialize allocations. Overwrite freed allocations 0 1 Bit 5 = Do not overwrite freed allocations. = Overwrite freed allocations. - Reserved (binary - Allocation value Char(1) - Freed value Char(1) - Reserved 0) Bits 6-7 (binary 0) Char(3) • Reserved (binary 9 Current 9 Total number of reallocations UBin(4) 9 Total number of frees UBin(4) 9 Total number of allocations UBin(4) 9 Maximum number 9 Size of the heap space in 9 Number marks • Total The first number 0) of outstanding allocations UBin(4) of outstanding allocations of outstanding number Char(64) UBin(4) pages UBin(4) UBin(4) of extensions UBin(4) 4 bytes that are materialized identify the total number of bytes provided for use by the instrucThis value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes a materialization length (hex 3803) exception. tion. The second 4 bytes that are materialized identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No exceptions (other than the materialization length exception described previously) are signaled in the event that the receiver contains If insufficient area for the materialization. operand 3 is equal to hex 01, then the mark template information is added to the heap space attributes template information. The mark template information is repeated for the number of outstanding marks. This information follows the heap space attributes template information. The format of the If mark template information is as follows: Chapter 7. Heap Management Instructions 7-1 Materialize — Mark Given the mark If Attributes (MATHSAT) Mark template information • all Heap Space of list mark identifiers with a identifier N, that allocation also N> mark identifier being entry belongs to mark N and a allocation belonging to where X has values 1 to N-1 identifier N-X, operand number 3 is equal to hex 02, then the allocation template information is added to the heap space and mark template information. The allocation template information is repeated for current of outstanding allocations. This information follows the mark information template. Allocation template Char(48) — Space pointer Allocation address — Mark identifier - Allocation size Space pointer — Char(12) UBin(4) Reserved mark identifier is null, this allocation is not associated with any mark. most recent mark identifier to which the allocation belongs. If The heap identifier Heap — Identifier Activation — Heap The is Template Group Mark group mark contains the is not null in the space. The format it as follows: Char(8) UBin(4) identifier UBin(4) identifier activation tifier is in If it template identified by operand 2 must be 16-byte aligned of the template specified by operand 2 ° for 1. attributes • Space pointer identifier identifier may be zero, indicating the heap space specified by the heap iden- the current Activation Group, MATHSAT will to materialize if a program attempts an activation group to which the program does signal an activation group access violation (hex 2C12) exception heap space attributes of a heap space in not have access. Operands 1, 2 and 3 are not modified by the instruction. Events 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor time exceeded 0801 Process storage limit exceeded 0016 Machine observation 0101 Instruction reference 0401 Domain violation 0402 Hardware storage violation Chapter 7. Heap Management Instructions 7-19 Materialize | 0017 Damage set | 0401 System object | 0801 Partial system object | Heap Space Attributes (MATHSAT) damage set damage set Exceptions Operands Exception 06 01 08 space addressing violation 3 X X X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X X X X Argument/parameter parameter reference violation Damage encountered damage state 05 authority verification terminated due to 44 partial system object damaged object X damage X 04 object storage limit limit X exceeded X X 02 machine check X 03 function check X Pointer specification does not exist 02 pointer type invalid X X X X X X X X X X 03 Pointer addressing invalid object 32 Program execution 12 Activation group access violation X 13 Activation group not found X Scalar specification 03 Scalar value invalid 38 X Template specification 03 Materialization length 44 Domain 01 45 X Machine support 01 pointer 2C X exceeded 09 auxiliary storage pool number invalid 24 X Machine-dependent exception 03 machine storage 20 Other X 04 system object 1C 2 02 boundary alignment 01 10 1 Addressing specification Domain Heap X Violation X X X specification 01 Invalid Heap Identifier X Chapter 7. Heap Management Instructions 7-20 Materialize Heap Space Attributes (MATHSAT) Operands Exception 02 Invalid Request 1 2 3 Other X X 05 Heap Space Destroyed X 06 Invalid Heap Condition Chapter 7. X Heap Management X X Instructions 7-21 Reallocate Heap Space Storage (REALCHSS) Reallocate I | I Op Code 03BA Operand 1 Space allocation (Hex) | Operand 2 Size of space reallocation I | Heap Space Storage (REALCHSS) Operand /: Space Operand 2: Binary(4) scalar. — ILE access REALCHSS pointer. — — ( space_al location : si : : ) space pointer; ze_of_space_real location signed binary space pointer /* space_real 1 ocation */ A new heap space storage allocation of at least the size indicated by operand 2 is prosame heap space as the original allocation, which is indicated by operand 1. The operand 1 space pointer is set to address the first byte of the new allocation, which will begin on a boundary at least as great as the minimum boundary specified when the heap space was created. Description: vided from the Each allocation associated with a heap space provides a continuum of contiguously addressable bytes. Individual allocations within a heap space have no addressability affinity with each other. The maximum single allocation allowed is determined by when the heap space was created. The maximum single Storage that maximum single allocation size specified allocation possible is 16M-64K bytes. same mark/release status as the original allocation. If the new allocation carries the same mark and will be released by a Heap Space Storage from Mark (FREHSSMK) which specifies that mark identifier. is reallocated maintains the original allocation Free The the original was marked, the heap space storage allocation will be freed. Subsequent references to the original allocation will cause unpredictable results. The contents of the • If the new original allocation are preserved in the following fashion: allocation size ginal allocation will is appear greater than the original allocation size, the entire contents of the oriin the new allocation. The contents of the rest of the new allocation are unpredictable unless initialization of heap allocations was specified when the heap space was created. * If the will new allocation size contain at least as REALCHSS is less then or equal to the the original allocation size, the new allocation of the original allocation contents as the new allocation size allows. much to reallocate a domain violation (hex 4401) exception if a program running user heap space storage in a heap space with a domain of Common System. Operand not modified by the instruction. 2 will signal is state attempts Events 000C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded Chapter 7. Heap Management Instructions 7-22 Reallocate Heap Space Storage (REALCHSS) 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor time exceeded 0801 Process storage limit exceeded 0016 Machine observation 0101 Instruction reference 0401 Domain violation 0402 Hardware storage violation 0017 Damage set 0401 System object damage set damage 0801 Partial system object set Exceptions Operands Exception 06 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X Argument/parameter XXX XXX XXX 01 08 01 10 space addressing violation parameter reference violation Damage encountered 04 system object damage state 05 authority verification terminated due 44 1C partial 24 to damaged X object system object damage Machine-dependent exception 03 machine storage 20 limit exceeded X Machine support 02 machine check X 03 function check X XXX XXX Pointer specification 01 pointer does not exist 02 pointer type invalid X 03 Pointer addressing invalid object 44 Domain 01 45 Other 1 Addressing specification Domain Heap X Violation X specification X 02 Invalid Request Chapter 7. Heap Management Instructions 7-23 Reallocate Heap Space Storage (REALCHSS) Operands Exception 03 Heap Space 1 2 Other X Full 04 Invalid Size Request X 05 Heap Space Destroyed X 06 Invalid Heap Condition X Chapter 7. X Heap Management X Instructions 7-24 Set Set Heap Space Storage Op Code Operand 1: Space pointer data Operand 2: Binary(4) scalar. — Mark (SETHSSMK) Operand 1 Mark Identifier (Hex) 03B6 Heap Space Storage Mark (SETHSSMK) Operand 2 Heap Identifier object. ILE access SETHSSMK var mark_identi tier var heapjdenti fier : : space pointer ; signed binary ) Description: operand The heap space identified by operand 2 is marked and the mark identifier is returned in 1. Marking a heap space allows a subsequent Free Heap Space Storage from Mark (FREHSSMK) instrucusing the mark identifier returned in operand 1, to free all outstanding allocations that were performed against the heap space since the heap space was marked with that mark identifier. This relieves the user of performing a Free Heap Space Storage (FREHSS) for every individual heap space tion, allocation. A heap space may have multiple marks. The heap identifier specified in operand 2 is the identifier that was returned on the Create Heap Space (CRTHS) instruction. An attempt to mark the default heap space (heap identifier value of 0) will result in a invalid request {hex 4502) exception. An attempt to mark a heap space that has been created to not allow a Set Heap Space Storage Mark will result in a invalid request (hex 4502) exception. Operand 2 is not modified by the instruction. Events 000 C Machine resource 0201 Machine auxiliary storage threshold exceeded 0501 Machine address threshold exceeded 000D Machine status 0101 Machine check 0401 Auxiliary storage device requires service 0010 Process 0701 Maximum processor time exceeded 0801 Process storage limit exceeded 0016 Machine observation 0101 Instruction reference 0401 Domain violation 0402 Hardware storage violation 0017 Damage set Chapter 7. Heap Management Instructions 7-25 Set Heap Space Storage Mark 0401 System object damage set damage 0801 Partial system object (SETHSSMK) set Exceptions Operands 1 Exception 06 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X X X 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object damage state 05 authority verification terminated due to damaged object 44 1C X 04 object storage limit iimit exceeded X exceeded X X Machine support X 03 function check X Pointer specification does not exist 02 pointer type invalid X X X X 03 Pointer addressing invalid object Domain 01 45 X 02 machine check 01 pointer 44 X Machine-dependent exception 09 auxiliary storage pool number invalid 24 X X system object damage partial 03 machine storage 20 Other Addressing specification Domain Heap X X Violation X specification 01 Invalid Heap X Identifier 02 Invalid Request X 03 Heap Space X Full 05 Heap Space Destroyed X 06 Invalid Heap Condition X Chapter 7. Heap Management X X Instructions 7-26 Program Management Chapter 8. Program Management This chapter describes betic order. all instructions used for For an alphabetic summary of all Instructions Instructions program management. These instructions are the instructions, see Appendix A, in alpha- “Instruction Summary” Materialize Bound Program (MATBPGM) (MATPG) Materialize Program © Copyright IBM Corp. 1991, 1993 8-3 8-24 8-1 Program Management Instructions : Chapter 8. Program Management Instructions 8-2 Materialize Materialize Bound Program (MATBPGM) Bound Program (MATBPGM) I Op Code Operand (Hex) 02C6 1 Materialization request template Operand 1: Space Operand 2: System — Operand 2 Bound Program or Bound Service Program pointer. pointer. ILE access MATBPGM ( request_template var bound_program : : space pointer system pointer ) The bound program or bound service program Description: according to the specifications provided by operand identified by operand 2 is materialized 1. system pointer that identifies the bound program or bound service program to be mate2 does not refer to a program object, an object not eligible for operation (hex 2403) exception will be signaled. If Operand 2 refers to a program, but not to a bound program or bound service program, then a program not eligible for operation (hex 220A) exception will be signaled. Operand 2 is rialized. If Operand a The values in the materialization relate to the current attributes of the materialized bound program. Components are the materializable parts of a bound program or bound service program. Components may not be available for materialization because they were not encapsulated during bound program creation. Other components may not be available for materialization because they contain no data. Note: The bound program materialization request template takes the form of a variable length array of materialization requests. Template size specification Char(8) - Number UBin(4) of bytes provided - Reserved Number UBin(4) of materialization requests Reserved (binary Char(4) 0) Array of materialization requests Char(‘) - Space pointer Receiver - Bound Program - materialization options Char(4) General Bound Program materialization options Char(2) • General bound program information 0 1 i Char(4) (binary 0) Reserved for IBM Bit 0 = Do not materialize = Materialize Internal Use Only. If used, unpredictable results may occur. Chapter 8. Program Management Instructions 8-3 Materialize • Reserved • Program copyright Strings 1 1 0 1 1 1 0 1 0 ! 1 0 1 0 1 Bits 7-11 0 1 1 Reserved (binary 1 • = Do not materialize = Materialize the program if - Materialization options • Reserved (binary • Signatures information 1 Bits 1-7 Char(1) 0) = Do not materialize = Materialize the program if is = Do not materialize = Materialize the program if is 1 1 1 = Do not materialize = Materialize the program if Reserved (binary is Bit 0 Bit 1 a bound service program. Bit 2 a bound service program. Exported program data information 0 8 bound program and not a bound service program. Exported program procedure information 0 • a Bound Service Program Specific • is Bit 0 0) - 1 Char(1) bound program information Reserved (binary 0 Bits 14-15 0) Bound Program materialization options Specific 0 1 Bit 13 = Do not materialize = Materialize Specific • Bit 12 = Do not materialize = Materialize 1 9 1 1 Activation group data exports 1 Bit 6 = Do not materialize = Materialize 1 1 Bit 5 limits Activation group data imports 1 component = Do not materialize = Materialize • 0 Bit 4 string directory Reserved • Bit 3 = Do not materialize = Materialize • 1 1 Bit 2 = Do not materialize = Materialize Bound program • 1 = Do not materialize = Materialize Bound program • 1 I Bit Bound modules information • 1 — 1 Bound service programs information • 1 _ Bound Program (MATBPGM) a Bit 3 bound service program. Bits 4-7 0) Chapter 8. Program Management Instructions 8-4 Materialize — Bound - Bound Program (MATBPGM) Modules materialization options Char(4) General module information 0 = Do 1 = Bit 1 not materialize Reserved - Module 1 0 Materialize - 0 Bit 1 string directory component Bit 2 = Do not materialize = Materialize Bits 3-10 - Reserved - Reserved (binary 0) Bits 11-17 - Module copyright strings Bit 18 0 1 - 1 = Do not materialize = Materialize Reserved (binary Bits 19-31 0) — Bound Module materialization number — Reserved (binary 0) UBin(4) Char(4) Description of bound program materialization request template fields: Each of the reserved fields must be set to binary zeroes, or a template value invalid (hex 3801) exception will be signaled. | | Number of bytes provided | This is the size in bytes of the materialization request template. If this size does not corre- j spond to the actual number of bytes in the materialization request template, then a template | value invalid (hex 3801) exception will be signaled. This does not include any storage for returned data. That storage is pointed to by the receiver values. | | Number of materialization requests | The number of requests the array of materialization requests in is specified by this value. If j number is greater than the actual number of materialization requests provided, then a template value invalid (hex 3801) exception will be signaled. this | | Materialization requests I an array of materialization requests. A materialization request consists of one or and an optional module number specified to be materialized into the corresponding receiver. Each materialization request consists of the following fields. This | is more j ! bits, Receiver | is a pointer to a space which will hold the materialized data. The space pointed to must be aligned on a 16-byte boundary, and must be at least 8 bytes long. This is so that it can hold the bytes provided and bytes available field of This | I j the receiver. If the space is not at least 8 bytes long a template value invalid | | (hex 3801) exception Bound Program will be signaled. materialization options | This bit mapped field specifies the parts of the bound program object to be mate- j rialized. A options. If program bound module materialization request need not specify any j no bits are set, a bit must be set in the materialization materialization | options j field, or a template value invalid (hex 3801) exception will be signaled, may be specified. When multiple options are specified, all of the Mutiple options j | be materialized into one receiver. The pieces requested on be placed in the receiver in the order that the option bits are defined. For example, if all data is requested, the general bound program information will be the first item in the receiver and the exported program data requested data will the materialization [ | I will Chapter 8. Program Management Instructions 8-5 Materialize information will be the last item. module materialization options options are also specified on the bound field, the materialized data for those options If follow that data materialized for the bound program The bound program materialization options are materialization 1 Bound Program (MATBPGM) will materialization options. split into three distinct bit sets. The general bound program materialization options contains bits that represent data that can be materialized for either bound programs or bound service programs. 2 The specific bound program materialization options contains bits that represent data that can be materialized only for bound programs, and not for bound service programs. 3 The specific bound service program materialization options contains bits that represent data that can be materialized only for bound service programs. If a bit is on to materialize information that program being materialized, then an materializable case, will will be provided in not contained is in the type of bound indication that the information the receiver header. No is exception, not in this be signaled. Each of the requested pieces will be placed on a 16-byte boundary within the receiver. The general bound program information field specifies that general information about the bound program object should be materialized. The program copyright strings field specifes that the collected program copyright strings of the constituent bound modules should be materialized. The bound service programs information field specifies that information about the service programs bound to the materialized bound program should be materialized. These bound service programs are those that contain exports that resolve to imports in the materialized bound program. The bound modules information field specifies that information about the modules bound into the materialized bound program should be materialized. The bound program string directory component field specifies program string directory should be materialized. The bound program limits field specifies that the current sizes that the bound and maximum values of the bound program components should be materialized. The activation group data imports data imports resolving to weak field specifies that information about those activation data exports is be materialized. The activation group data exports field specifies that information about those data exports promoted to the activation group is to be materialized. The specific bound program information field specifies that information specific to a bound program, and not to a bound service program, should be materialized. The signatu res information field specifies that the bound program signatures should be materialized. The exported program procedure information field specifies that the exported procedures specified during program creation should be materialized. 2 Referential extensions are data streams that are not included in the creation templates, but are pointed to by a the template. space pointer in Chapter 8. Program Management Instructions 8-6 Materialize Bound Program (MATBPGM) The exported program data information field specifies that the exported data specified during program creation instruction should be materialized. Bound Module This Materialization Options bit mapped field specifies that are to be materialized. the parts of the modules bound into the program A module any materialization options, if no program materialization options exception will be signaled. field, materialization request need not specify are set, a bits bit must be set in the bound or a template value invalid (hex 3801) may be Multiple options specified. When multiple be materialized into one receiver. The pieces requested on the module materialization will be placed in the receiver in the order that the option bits are defined. For example, if all data options are specified, all of the requested data will is requested, the general module information will be the first item in the receiver and the module string directory component will be the last item. If options are also specified on the bound program materialization options field, the materialized data for those options will precede that data materialized for the bound module materialization options. In addition, each of the requested pieces will be placed on a 16 byte boundary within the receiver. that general information about the The general module information field specifies module object should be materialized. The module string directory component field specifies that the string directory of the associated module(s) should be materialized. The module copyright strings field specifies that the module copyright strings should be materialized. Bound Module Number Bound Module Materialization is on, then through the number of modules bound into the program; or 0, to materialize information about all modules bound into the program. If this number is greater than the number of modules bound into the program, then a template value invalid (hex 3801) excepIf at least this is the tion will one bit of the number of the module Materialization Options field to materialize, from 1 be signaled. The information that is materialization options materialized is specified in the bound module field. no bits of the bound module materialization options field are on, then no module information is being materialized, and this field must be binary 0 or If template value invalid (hex 3801) exception will a be signaled. Format of materialized data Format of Receiver • Number of bytes provided for materialization UBin(4) • Number of bytes available for materialization UBin(4) • Reserved (binary « Materialized data Char(8) 0) Char(*) Bytes provided providing to hold the materialized data. It must be equal to eight, then no data will actually be materialized, and the number of bytes required to materialize the requested data will be placed in bytes available. If the value provided is greater than eight, but less than the number of bytes required to hold the requested data, the data will be truncated and no exception will This is the number of bytes the user greater than or equal to eight. If it is is Chapter 8. Program Management Instructions 8-7 Materialize be signaled. Note that a value greater than eight, being materialized, since bytes 9-16 are reserved. If Bound Program (MATBPQM) but less than 16 will result in no data the receiver data is smaller than the size indicated by bytes provided, and the materialized larger than the space provided in receiver, the space addressing (hex 0601) excepis be signaled unless receiver is an automatically extendable space object. an automatically extendable space object, the space will be extended, up to its tion will is If receiver maximum size. Bytes available bytes provided If used greater than eight, this contains the is for the materialization, including bytes provided number of bytes that have any reserved bytes or bytes used been padding. for If equal to eight, this contains the total size of the receiver needed to hold the requested materialization. A value of zero is returned if there is no data to materialize. is Materialized data For each bit on in the bound program materialization options and bound module materialization options, this will contain the associated data. Each entry will be preceded by a common header which identifies the type of data and the offset to the next entry. When multiple bits are on in the same request, the data is returned in the order defined by the bound program No exception is materialization options and the signaled when bound module materialization options. the size of the receiver, as specified by bytes provided is not enough to hold data for all requested bound program materialization options and bound module materialization options. Instead, the data is truncated and bytes provided only reflects the actual amount of data returned. One of several conditions may arise, each large with a different result, the receiver If that is enough not large bound program next entry the bytes available offset to to hold the materialization header, materialization option or bound module no data is returned for materialization option. The the previous materialization header, if one exists, is set to 0, and field is set to reflect the amount of data actually materialized for the bound program materialization options or bound module materialization options that have already been processed. Bytes available will be set to 8, or bytes provided field in ', less, if the receiver is not big enough to hold the first whichever is materialization header. the receiver is big enough to hold the materialization header, but not big enough to hold of the data requested by the bound program materialization option or bound module materialization option, the partial data flag will be set in the materialization header If all and as which there is room. For data which consists of one continuous stream 3 the receiver will be filled and bytes available will equal bytes provided. For data which consists of an option specific header followed by an array of homogenous elements 4 data will be returned in such a way that no partial option specific header or array element will be returned. If there is not enough room to hold the entire option specific header, none of it will be returned. If there is room for the option specific header, but not much data all will be returned for of the entries, only those entries that will the option specific header number will reflect of entires available data returned and may in the fit the module. be returned. The number of entries in of entries returned rather than the actual will number Bytes available will reflect the actual amount of Note that because many option specific not equal bytes provided. headers and entries are larger than the common materialization header, there than one option for which partial data is returned. 3 The items that fall nent, module category are general bound program information, bound program limits, specific bound program bound service program information, general module information, bound program string directory compodirectory component and module copyright strings. into this information, specific 4 may be more string The items which fall into this catagory are bound service programs information, bound modules information, signatures information, program copyright strings, exported program procedure information, activation group data imports, activation group data exports, and exported program data information. Chapter 8. Program Management Instructions 8-8 Materialize Bound Program (MATBPGM) Format of Common Materialization Header UBin(4) • Offset to next entry » Bound Program materialization • Bound Module materialization - Bound Module materialization number • Flags Char(4) - Bit 0 Char(4) identifier UBin{4) identifier Entry presence 0 1 - Char(4) identifier = No data present for entry = Data present for entry Bit Partial data 0 1 = = data All in materialization Partial data 1 was returned was returned because was too receiver small to hold all data for the requested option - Bit 2 Valid Materialization data 0 = The 1 = The data requested in this materialization request is never present for the type of bound program being materialized. data requested materialization request in this may be present for the type of bound program being materialized. — • Reserved (binary Reserved (binary Bits 3-31 0) Char(12) 0) Offset to next entry This contains the offset from the beginning of this entry to the beginning of the next entry. will contain zero if this is the last entry. It Bound Program materialization identifier bit This indicates which portion of the bound program is contained in this entry. It is the being data this resulted in which was on in bound program materialization options that materialized. Either no bits, or a single bit of this field will be on. If no bits of this field are on. then the data contained in this entry indicated by the is bound module materialization identifier field. Bound Module materialization identifier This indicates which portion of the module, indicated by the bound number identifier field, is contained in this entry. It is the bit which module materialization options single entry bit is or no of this field will be on. bit indicated by the bound program then that type of information Bound Module If a the be If field that will resulted If no in this bit is number identifier bit of the bound module materialization module for which information has been in data being materialized. on, then the data contained materialization be returned module materialization was on in the bound identifier field. If a bit is is the Either a in this set on, the entry. materialization identifier field is on, materialized in then this this entry, and number of this field will not 0. no bits of the bound module materialization identifier field are on, then this field will be 0. Flags This field specifies information about the item being materialized. whether there is data available for the requested item. items may not be encapsulated into the object, so no data will be returned when their The entry presence Some materialization is field specifies requested. Chapter 8. Program Management Instructions 8-9 Materialize Bound Program (MATBPGM) The Partial data field specifies that only a portion of the data was returned because space was not present in the receiver to hold all of the data cient for the suffi- requested materialization option. The M iid materialization field specifies whether the requested information is valid to be materialized for the type of bound program that is being materialized. For example, specific bound program information is not valid for a bound service program. Even if data may be present for the type of bound program being materialized does not mean that it actually is Refer to the entry present field to see if it is. Format of materialized general bound program information • Length • Reserved • Number • Activation group attributes — bytes of materialization in UBin(4) 1 Char(264) of secondary associated spaces UBin(4) Char(4) Target activation group 0 1 2 3 Char{1) — Default activation group = Caller's activation group = Named activation group = Unnamed activation group 4-255 reserved — Reserved 1 Char(3) 8 Activation group 9 Reserved 9 Coded character • Composite language version 5 9 Composite version on which module creations occurred 5 9 Composite machine version 5 9 Creation target version 5 • Version on which creation occurred 5 • Bound program name Char(30) 1 Char(14) set identifier UBin(2) UBin(2) UBin(2) UBin(2) UBin(2) UBin(2) identifier Char(1) = reserved = 1 Bound Program 2 = Bound Service Program 3-255 = reserved 0 9 Compression status — - 5 All Char(1) Executable portion 0 = versions are represented as 16 - Bits 0-3 - Bits 4-7 Bit 0 Executable portion bit is values not compressed mapped as follows Reserved (binary 0) Version - Bits 8-11 - Bits 12-15 Release Modification Chapter8. Program Management Instructions 8-10 Materialize - — = 1 Executable portion Bit - 0 = Observable portion is not - 1 = Observable portion is compressed Reserved Length compressed Observable portion — Reserved ® is in 1 compressed Bits 2-7 (binary 0) Char(178) 1 bytes of materialization This will Number Bound Program (MATBPGM) of the is number of bytes materialized. For the general bound program information this always be a constant 512. secondary associated spaces currently associated with the is the number of secondary associated spaces object. This Activation group attributes The activation group attributes specify characteristics program will be activated. of the activation group into which the Target activation group or This is the target activation group value specified when the bound program bound service program was created. name Activation group This is the activation group name specified when the bound program or bound service program was created. Coded character This set identifier is the CCSID value of the bound program or bound service program. Composite language version for the the earliest version of the operating system on which the languages used 6 of composite This is a saved. be object to program bound bound modules will allow the program. this into bound modules of the language versions of the This is all Composite version on which module creations occurred modules bound into This is the earliest version of the operating system on which all of the 6 version-on-which-modulethe program can be re-created. This is a composite of all of the program. this into bound modules the of versions creations-occurred Composite machine version allow the the earliest version of the operating system on which the machine will 6 of the versions machine the of bound program to be saved. This is a composite of all This is modules bound into this program. Creation target version program object This is the version of the operating system for which the bound was created. Version on which creation occurred object was created. This is the version of the operating system on which the bound program Bound program This 6 A composite identifier field identifies version is level compatibility, this the type of bound program being materialized. the composite. Given backdefined to be the latest version, in time, of all of the versions comprising versions would be would be the earliest version of the operating system on which all of the comprising compatible. Chapters, Program Management Instructions 8-11 Materialize Bound Program (MATBPGM) Compression status This field identifies whether the executable or the observable portions of the or bound service program are compressed. | Format of materialized program copyright strings • Length • Version of copyright creation extension • Number * Reserved | | | | « I I I -L Length bytes of materialization of copyright statements in Ubin(4) Ubin(4) the pool Ubin(4) Char(4) Char(*) bytes of materialization This is the number of bytes materialized. in Version of copyright creation extension This is the version of the copyrights when the module was created. Number of copyright strings in the pool. This I I in Copyright string pool I I bound program is the number of copyright strings that follow. Copyright statement pool. This is the data for all of the copyright strings. Each copyright string consists of a 4 byte length followed by the text of the string. The length reflects the actual length of the copyright string and does not include the length of the length field. All copyright strings along with their lengths are placed contiguously in the buffer with no intervening I I I padding Format of the materialized bound service programs information 3 Length * Number * Reserved (binary * Array of bound service program records in bytes of materialization of sen/ice — Bound programs bound program UBin(4) 0) Char(8) Char(*) service program ID Char(24) Bound service program context object type Char(1) - Bound service program context object subtype Char(1) - Bound service program context name Char(10) - Bound service program object type Char(1) - Bound service program object subtype Char(1) Bound service program name Char(10) — Referentially — Reserved (binary in to this - - Length UBin(4) bound program signature Char(16) 0) Char(8) bytes of materialization The number of bytes materialized. This will be 16 + (N * 48) where N is the number of bound servide programs- those programs that contain exports that resolve imports in the bound program. Number of service This is programs bound to this program number of bound service programs bound the to the Chapter 8. bound program. Program Management Instructions 8-12 Materialize Bound Program (MATBPGM) Array of bound service program records This array contains one record for each bound service program bound to the bound program. Each record contains the following information Bound service program context type This is the object type of the context with the given name. Bound service program context subtype This is the object subtype of the context with the given name. Bound service program context name the context specified during program creation where this bound service program was found when the bound program was created. This value could be This is hex zeroes, in which case the name resolution the given bound service program. set with all list is used to locate Bound service program type This is the object type of the program with the given name. Bound service program subtype This is the object subtype of the program with the given name. Bound service program name This is the name of the bound service program specified during program creation. Bound service program signature is the signature of the bound service program that against the current signature of the bound program. This was used to match Format of the materialized bound modules information UBin(4) bytes of materialization • Length 9 Number • Reserved (binary • Array of bound module records Char(*) — Bound module ID Char(60) qualifier Char(30) — Length in of modules bound Number UBin(4) program Char(8) 0) - Module - Module name Reserved (binary in into this Char(30) Char(20) 0) bytes of materialization The number of bytes materialized. This of modules bound into the modules bound into this This is the number of will be 16 + (N * 80) where N is the number of bound program. program modules bound into the bound program. Array of bound module records This array contains one record for each module bound into the bound program. Each record contains the following information Module qualifier the qualifier specified during program creation where this module was found when the bound program was created. The module qualifier is used to differentiate between two different modules of the same name. This usually conThis is tains a context name. Chapter 8. Program Management Instructions 8-1 Materialize Bound Program (MATBPGM) Module name This is name the of the module. Format of the materialized bound program string directory component • Length • Reserved (binary • String Pool — in bytes of materialization 0) Char(12) Char(*) Length of the string — CCSID - String Length UBin(4) in UBin(4) of the string UBin(2) Char(*) bytes of materialization The number of bytes materialized. This be 16 will + the length of the string String Pool A memory area containing the strings defined for this program. It can be of any length It contains a series of strings and lengths. String IDs specified other materialized components can be used as indexes into this addressable by a UBin(4). string pool. Length of string The length of the next string. This field contains the length of the string only, and does not include the length of the either the length or the CCSID field. The length field of a string is not subject to alignment considerations. CCSID of string The character code set which CCSID is the CCSID of a string field identifier of this string. is This string module object from which of the is encoded in the given CCSID, this string is originally declared. The not subject to alignment considerations. String Character buffer which contains one Format of the materialized bound program string, Its Length • Reserved (binary • Current size of bound program • Maximum number • Current • Maximum number • Current • Maximum number • Current number of service programs bound to program • Maximum - Current size of bound program string directory • Maximum • Current size of bound program copyright strings • Maximum number - Current • Maximum number bytes of materialization number number size of number UBin(4) UBin(4) of associated spaces UBin(4) modules bindable modules bound into program into string directory bound program copyright of auxiliary storage of auxiliary storage UBin(4) program of service programs bindable to bound program size of field. Char(12) of associated spaces of defined by the length UBin(4) 0) of is limits • in length strings segments segments of static storage frames UBin(4) program UBin(4) UBin(4) UBin(4) UBin(4) UBin(4) UBin(4) UBin(4) UBin(4) UBin(4) Chapters, Program Management Instructions 8-14 in Bound Program (MATBPGM) Materialize number Current • Maximum number • Current - Maximum number » Current ° Maximum number • Current • Minimum amount number number number of of of in UBin(4) UBin(4) program data exports program data exports UBin(4) of signatures UBin(4) UBin(4) of signatures Reserved (binary Length UBin(4) program procedure exports program procedure exports of of static storage required UBin(4) of static storage required UBin(4) Maximum amount • UBin(4) of static storage frames • Char(148) 0) bytes of materialization The number of bytes materialized. This Current size of bound program This is the current size, in will always be a constant 256. machine-dependent bound program being material- units, of the ized. Maximum number This of associated spaces maximum number the is of associated spaces allowed for the bound program being materialized. Current number of associated spaces This the current is number of associated spaces allocated to the bound program being materialized. Maximum number This of modules bindable the is into maximum number of program modules that can be bound into a bound program. Current number of modules bound into program This is the current number of modules bound into the bound program being materialized. programs bindable to program of bound service programs that can be bound to a bound program. These bound service programs contain exports to which imports from a bound program resolve. Maximum number This is of service the maximum number Current number of service programs bound to program This is the current number of bound service programs bound to the bound program being materialized. Maximum size of This bound program the is maximum string directory size, in bytes, of the bound program string directory. Current size of bound program string directory This is the current size, in bytes, of the bound program string directory. Maximum size of This bound program copyright is the maximum strings size, in bytes, of the bound program copyright strings. Current size of bound program copyright strings This is the current size, in bytes, of the bound program copyright strings. Maximum number This | | I is of auxiliary storage the segments maximum number of auxiliary storage segments allowed Current number of auxiliary storage segments This is the current number of auxiliary storage segments in for a bound program. the bound program being materialized. Chapter 8. Program Management Instructions 8-1 Materialize I Maximum number This I I This I This This bound proqram beina maximum number If of procedures that are allowed to be exported from a bound the bound program being materialized is not a bound service program then will be zero. number of procedures exported from the bound program being materialthe bound program being materialized is not a bound service program, then this value will be zero. If Maximum number This I of data exports the is program. this value I maximum number of data items that are allowed to be exported from a bound the bound program being materialized is not a bound service program then will be zero. If Current number of data exports This is the current number of data items exported from the bound program being materialzed ^the bound program being materialized is not a bound service program, then this value will be zero. I ' ! I ' Maximum number This I of signatures the is maximum number program being materialized I of signatures allowed for a bound program. If the is not a bound service program, then this value will bound be zero. Current number of signatures This number of signatures contained in the bound program being materialthe bound program being materialized is not a bound service program, then this value will be zero. I is ized. i I I of static storage frames required by the the current is ized. I I number Current number of procedure exports i I bound program. of procedure exports the is program. this value i I the current is Maximum number I I of static storage frames allowed for a materialized. I I frames maximum number Current number of static storage frames I I of static storage the is Bound Program (MATBPGM) Minimum amount This I the current If is of static storage required. the smallest amount of static storage that is required for the bound program or measure is in bytes. The actual amount of static storage that is be anywhere between the minimum and the maximum amounts of service program. This ma y storage, inclusive. used : I Maximum amount This required static of static storage required. the largest amount of static storage that may be required for the bound program or measure is in bytes. The actual amount of static storage that is used may be anywhere between the minimum and the maximum amounts of is service program. This required static storage, inclusive. Format of the materialized activation group data imports Length in Number bytes of materialization UBin(4) of activation group data imports Reserved (binary UBin(4) 0) Char(8) Array of activation group data imports - Char(*) String ID - Reserved UBin(4) (binary 0) Char(12) Chapter 8. Program Management Instructions 8-16 Materialize Length bytes of materialization The number of bytes materialized. This in vation group data imports contained in wilt + 1)*16, where be (N N is the number of acti- the bound program or bound service program. group data imports The number of activation group data imports contained service program. Number Bound Program (MATBPGM) of activation in the bound program or bound Array of activation group data imports This array contains one record for each data item contained in the program or bound service program. Each record contains the following information: String ID This is the identification used to extract the program name of this data item from the string directory. Format of the materialized activation group data exports UBin(4) bytes of materialization • Length • Number • Reserved (binary • Array of activation group data exports Char(*) — String ID UBin(4) — Strength of data item Char(1) in UBin(4) of activation group data exports Char(8) 0) - 0 = Reserved - 1 = Export Strongly - 2 = Export Weakly - 3-255 - Reserved = Reserved (binary 0) Char(3) — Length of data item UBin(4) — Reserved (binary Char(4) Length in 0) bytes of materialization The number of bytes materialized. This vation group data exports contained Number in will be (N + 1)*16, where N is the number of acti the bound program or bound service program. group data exports of activation group data exports contained service program. of activation The number in the bound program or bound Array of activation group data exports This array contains one record for each data item contained in the program or bound service program. Each record contains the following information: String ID This is the identification used to extract the program name of this data item from the string directory. Strength of data item This field indicates whether the activation group export is exported strongly or weakly. Length of data item. The size in bytes of the activation group export. Chapter 8. Program Management Instructions 8-17 Materialize | Bound Program (MATBPGM) Format of the materialized specific bound program information: Specific bound program information can only be materialized for bound programs, and not for bound service programs. • Length <* Reserved (binary | | • | bytes of materialization in UBin(4) 0) Char(12) Program entry procedure information - Module number containing program - Program entry procedure string ID Char(16) entry procedure UBin{4) UBin(4) - Minimum parameters - Maximum parameters — • | Reserved (binary Reserved (binary Length UBin(2) UBin(2) 0) Char(4) 0) Char(32) bytes of materialization in The number of bytes materialized. This I will always be a constant Module number containing program entry procedure This is the number, in the bound modules information, program entry procedure for this bound program. Program entry procedure This is of the 64. module which contains the string ID the string ID for the name of this program entry procedure. Minimum parameters This the is minimum number of parameters that the program entry procedure can accept. maximum number of parameters that the program entry procedure can accept. Maximum parameters This the is Format of the materialized signatures information: Signatures information can only be materialized bound service programs, and not for bound programs. • Length • Number ° Reserved (binary 8 Array of signatures — Length in bytes of materialization of signatures contained in UBin(4) the program UBin(4) 0) Char(8) Char(*) Signature in Char(16) bytes of materialization The number of bytes materialized, This tures contained Number for in of signatures contained in the This is the number will be (N + 1)*16, where N is the number of signa- the program. program of signatures contained in the program. Array of signatures This array contains one record for each signature contained in the program. Each record contains the following information. The first record contains the current signature. Signature A signature of the service program. Chapter 8. Program Management Instructions 8-18 Materialize Bound Program (MATBPGM) Format of the materialized exported program procedure information: Exported program procedure information can only be materialized for bound service programs, and not for bound programs. Length in UBin(4) bytes of materialization UBin(4) of exported procedures Number Reserved (binary Char(8) 0) Array of program exports Char(*) - String ID for procedure export UBin(4) — Export - Reserved (binary Length in UBin(4) number Char(8) 0) bytes of materialization The number of bytes materialized. This will be (N + 1)*16, where N is the number of exported procedures. Number of exported This is procedures the of procedures exported from the service program. number Array of program exports This array contains one record for each procedure exported from the service program. Each record contains the following information: String ID for procedure export is the identification used to extract the from the program string directory. This Export name of this exported procedure number This is the number of this exported procedure. Format of the materialized exported program data information: Exported program data information can only be materialized for bound service programs, and not for bound programs. UBin(4) bytes of materialization • Length • Number • Reserved (binary • Array of data exports Char(*) — String ID for data export UBin(4) — Export in in Char(8) 0) UBin(4) number - Reserved Length UBin(4) of exported data items Char(8) (binary 0) bytes of materialization The number of bytes materialized. This will be (N + 1)*16, where N is the number of exported data items. Number of exported data items This is the number of data items exported from the service program. Array of data exports This array contains one record for each data item exported from the service program. record contains the following information: Each String ID for data export This is the identification used to extract the name of this exported data item from the program string directory. Export number This is the number of this exported data item. Chapters. Program Management Instructions 8-19 Materialize | Bound Program (MATBPGM) Format of materialized general module information ® Length 9 Reserved 9 Reserved o Coded character j 1 1 I I 1 Char{12) Char{276) set identifier UBin(2) Reserved 9 Creation target version 5 9 Language version 0 Version on which creation occurred 5 0 VLIC version 5 9 Reserved 0 Number 1 Char(10) Char(2) 5 Char(2) Reserved o Reserved Char(2) Char{16) Char(16) Char(2) Reserved * Compiler name 9 Program entry procedure Char(2) Char(20) Program entry procedure Char(16) attributes Program entry procedure = = Char(4) exists BitO Program entry procedure does not exist in this module Program entry procedure exists in this module Reserved (0) Bits 1-31 Program entry procedure dictionary Program entry procedure 9 UBin{4) 1 9 1 Char(2) of secondary associated spaces 9 0 UBin(4) 1 o 1 I bytes of materialization in id UBin(4) string id UBin(4) Program entry procedure minimum parms UBin(2) Program entry procedure maximum parms UBin(2) Reserved Length in Char(124) bvtes of materialization This is the number of bytes materialized. always be a constant 512. Coded character For the general module information this will set identifier The CCS ID defines the code page of the symbols in the string directory. Language version This is the earliest version of the operating system on which language used to be saved. module object Creation target version This is the version of the operating system for which the module object was will allow the created. Version on which creation occurred This is the version of the operating system that was running on the system where the module object was created. Chapter 8. Program Management Instructions 8-20 Materialize Bound Program (MATBPGM) Earliest version This is the earliest version of the operating system on which the machine will allow the module object Number to be saved. secondary associated spaces This is the number of secondary associated space segments currently associated with the of object. Compiler name This identifies the compiler which translated the user's source language. Program entry procedure This identifies the program entry procedure Program entry procedure This bit if one is present in the module. attributes mapped field identifies attributes of the program entry procedure. The program entry procedure existence field specifies whether a program entry procedure is present in the module being materialized. Dictionary id of the procedure The dictionary id is used as a handle to uniquely name may be used identify the procedure. String id of the procedure The string id name from to extract the character string which is the procedure the string pool. Program entry procedure minimum parms This is the minimum number of parameters allowed by the program entry procedure. Program entry procedure maximum parms This is the maximum number of parameters allowed by the program entry procedure. Format of the materialized module string directory component Length in UBin{4) bytes of materialization Reserved (binary Char(12) 0) String Pool Char(*) - Length of the string UBin(4) - String Char(*) Length in bytes of materialization The number of bytes materialized. This will be 16 + the length of the string pool. String Pool area containing the strings defined for this module. It can be of any length addressable by a UBin<4). It contains a series of strings and lengths. String IDs specified other materialized components can be used as indexes into this string pool. A memory in Length of string This field contains the length of the string only, and does not include the length of the length field, itself. The length field of a string is not subject to The length of the next string. alignment considerations. String Character buffer which contains one string. Its length is defined by the length field. Format of the materialized module copyright strings: The format of the materialized module copyright strings is the same as for the materialized program copyright strings. Chapter 8. Program Management Instructions 8-21 Materialize Bound Program (MATBPGM) Template Value Invalid exception reason codes: This instruction supports setting of the optional reason code field in the exception data which can be retrieved when the 00 template value invalid excep01signaled. When the tion is first byte of the reason code is not zero, the exception is being signaled because one of the materialization receivers is not valid. Bound Program On Materialization Template {pointed to by operand 1 of this instruction) Size of template is not sufficient to hold number of requests specified. nth materialization request is not valid. 01 02 03 The receiver is not aligned on a 16 byte boundary. The materialization request bytes provided is less than 8. The materialization request contains no materialization options or invalid materialization options. the length of field data then no materialization options were specified and the offset in Otherwise, an invalid option was specified and the provided offset to field in bytes and offset in field in bits data will identify the invalid materialization option. The materialization request contains a module materialization number that is greater than the number of modules bound into the program. If field in bits 04 data will be is 8, 0. The materialization request contains a non-zero module materialization number module materialization options. The materialization request contains a non-zero reserved field. 05 06 , but no Authorization Required • Retrieve - Operand - Contexts 2 referenced for address resolution Lock Enforcement 3 Materialize - Operand - Contexts 2 referenced for address resolution Exceptions Operands 1 | Exception 06 01 08 2 space addressing violation X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X parameter reference violation Authorization 01 unauthorized for operation 10 Other Argument/parameter 01 0A 1 Addressing X Damage encountered 04 system object damage state X X 05 authority verification terminated due to damaged object 44 partial X system object damage X Chapter X 8. Program Management X X Instructions 8-22 Materialize Bound Program (MATBPGM) Operands Exception 1 1 2 Other Lock state X 01 invalid lock state 1 1C 1 Machine-dependent exception X 03 machine storage limit exceeded 1 20 22 1 -1 Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 04 object X X inelligible X 07 authority verification terminated due to destroyed object 0A program X object inelligible X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X 03 pointer addressing invalid object 1 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 X space extension/truncation 1 38 Template specification 01 template value invalid X X 02 template size invalid X X X 03 materialization length exception Chapter 8. Program Management Instructions 8-23 Program (MATPG) Materialize Materialize Op Code Program (MATPG) (Hex) Operand 0232 Operand Program 1 Attribute receiver Operand 1: Operand 2: Space 2 pointer. System pointer. ILE access MATPG ( receiver var program : : space pointer ; system pointer ) Description: operand The program identified by operand 2 is materialized into the template identified by 1. Operand 2 is a system pointer that identifies the program to be materialized. materialization relate to the current attributes of the materialized program. The template The identified by operand 1 The values in the must be 16-byte aligned. 4 bytes of the materialization template identify the total number of bytes provided in the temsupplied as input to the instruction and is not modified. A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. first plate. This value is The second 4 bytes of the materialization template are modified by the instruction to contain a value identifying the template size required to provide for the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified by the the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No exceptions (other than the materialization length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for the materialization. receiver. If The following attributes apply to the materialization of a program: * The existence * The obs ervation attribute indicates whether the program attribute field specifies the is temporary or permanent. template components of the programs that currently can be materialized. * the program has an associated space, then the space attribute is set to indicate either fixed- or initial value for the space is returned in the initial value of space field, and the size of space field is set to the current size value of the space. If the program has If variable-length; the no associated space, the size of space space * lf field field is set to a zero value, and the space attribute and initial value of values are meaningless. the program is addressed by a context, then the context addressability attribute is set to indicate and a system pointer to the addressing context is returned in the context field. If the program not addressed by a context, then the context addressability attribute is set to indicate this, and this, is binary 0's are returned ° lf the program this, is a in the context member and a system pointer field. of an access group, then the access to the access group is returned in group attribute the access group Chapter 8. is set to indicate field. Program Management If the program Instructions 8-24 Materialize is • member not a of an access group, then the access group attribute the access group binary 0's are returned in The performance class field is set to reflect is Program (MATPG) set to indicate this, and field. the performance class information associated with the program. - The user exit attribute defines if the referenced program is allowed to be used as a user exit program. of the program template may not be present if they have been removed by the Delete Program Observability instruction. Also, a template component will not be available if the program was created with its corresponding observation attribute in the Create Program template set to binary 0. If a template component cannot be materialized, 0's are placed in the fields of the program template that describe the size and offsets to that component. Components The offset to the OMT component field specifies the location of the OMT component in the materialized program template. The OMT consists of a variable-length vector of 6-byte entries. The number of entries is identical to the number of ODV entries because there is one OMT entry for each ODV entry. The OMT entries correspond one for one with the ODV entries; each OMT entry gives a location mapping for the object defined by its associated ODV entry. The following describes the formats » OMT — for an OMT entry: entry Char(6) Addressability type Char(1) Hex 00= Base addressability is from the start of the addressability is from the start of the automatic storage area Hex 02= Base addressability is from the start of the storage area addressed by a space Hex 03= Base addressability is from the start of the storage area of a parameter Hex 04= Base addressability is from the start of the storage area addressed by the space Hex 01 = Base static storage pointer pointer found in the process communication object attribute of the process executing the program Hex FF= Base addressability not provided. The object is contained in machine storage areas which addressability cannot be given, or a parameter has addressability to an object that is in the storage of another program to — Offset from base Char(3) For types hex 00, hex 01, hex 02, hex 03, and hex 04, this is a 3-byte logical binary value representing the offset to the object from the base addressability. For type and hex FF, the value — Base is binary 0. addressability For types hex 02 and hex 03, this Char(2) is a 2-byte binary field containing the number of the OMT entry for the space pointer or a parameter that provides base addressability for this object. For types hex 00, hex 01, hex 04 and hex FF, the value is binary 8. Program Management 0. Authorization Required • Retrieve — Operand — Contexts 2 referenced for address resolution Chapter Instructions 8-25 Materialize Program (MATPG) Lock Enforcement • Materialize — Operand — Contexts 2 referenced for address resolution Exceptions Operands Exception 06 space addressing violation X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X parameter reference violation Authorization 01 unauthorized for operation 10 X Damage encountered 04 system object damage state X X 05 authority verification terminated due to damaged object 44 1 partial X 22 24 X X Machine-dependent exception limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid 03 pointer addressing invalid object 2E X Lock state 03 machine storage 20 X X system object damage 01 invalid lock state 1C Other Argument/parameter 01 0A 2 Addressing 01 08 1 Resource control X X X X X limit 01 user profile storage limit exceeded X Chapter 8. Program Management Instructions 8-26 Materialize Program (MATPG) Operands Exception 36 Space 01 38 1 2 Other management space extension/truncation X Template specification 03 materialization length exception X Chapter 8. Program Management Instructions 8-27 Program Execution Chapter 9. Program Execution Instructions Instructions This chapter describes the instructions used for program execution control. These instructions are alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction in Summary.” Activate Program 9-3 Call External 9-5 (ACTPG) (CAL LX) Call Internal (CALLI) Clear Invocation Exit (CLRIEXIT) Deactivate Program (DEACTPG) 9-9 9-11 9-12 End (END) 9-14 (MATACTAT) Materialize Activation Group Attributes (MATAGPAT) Modify Automatic Storage Allocation (MODASA) 9-15 Materialize Activation Attributes 9-19 9-23 Return External (RTX) 9-25 Set Argument 9-27 List Length (SETALLEN) Set Invocation Exit (SETIEXIT) 9-29 Store Parameter List Length (STPLLEN) 9-31 Transfer Control (XCTL) 9-33 © Copyright IBM Corp. 1991, 1993 9-1 Program Execution Chapter 9. Program Execution Instructions Instructions 3-2 Activate Program (ACTPG) Activate Op Code Operand 1 Program or static storage frame (Hex) 0212 Operand 1: Space pointer data Operand 2: System — Program (ACTP6) object, Operand Program 2 system pointer. pointer. ILE access ACTPG ( var activation var program : : system pointer ; OR space pointer ; system pointer ) Warning; The following information is subject to change from release and be prepared to adjust for changes with each new release. to release. Use it with caution Description: This instruction creates an activation entry for the program specified by operand 2, if it uses static storage. If the program specified is a bound program, an invalid operation for program (hex 2C1 5) exception is signaled. No operation is performed for a program which does not require static storage. Operand 1 receives either a space pointer or system pointer as follows: If an activation entry is created or an activation entry exists for the program within the target activation group, then a space pointer to the static storage frame is returned. The static storage frame is allocated and initialized according to specifications within the program. The static storage frame is • 16-byte aligned and begins with a 64-byte header. by the machine. The header is the program does not use program pointer in operand static If an attempt If is made mark the activation • the static storage frame pointer is not initialized storage (hence, no activation entry of the activation entry is is and it is not used is created) a copy of the returned. to activate an already active • A space 2 The header provided for compatibility with prior machine implementations. is program then unchanged, and reinitialized machine object may not be specified for operand 1. Authorization Required • Operational — Program 8 referenced by operand 2 Retrieve — Contexts referenced for address resolution Chapter 9. Program Execution Instructions 9-3 Activate Program (ACTPG) Lock Enforcement e Materialize - Contexts referenced for address resolution Exceptions 1 Operands Exception 06 | 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X space addressing violation Authorization X 01 unauthorized for operation 10 Damage encountered X 04 system object damage state 05 authority verification terminated due to 44 1 partial damaged 22 24 X Machine-dependent exception limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification does not X exist X Program execution X 15 invalid operation for program Resource control limit 01 user profile storage limit 36 X X 03 pointer addressing invalid object 2E X X 02 pointer type invalid 1 X Lock state 01 pointer 2C X X system object damage 03 machine storage 20 X object 01 invalid lock state 1C Other Addressing 01 0A 1 X exceeded Space management Chapter 9. Program Execution Instructions 9-4 Call External (CALLX) Operands Exception 01 1 2 Other X space extension/truncation Chapter 9. Program Execution Instructions 9-5 Call External Call External Op Code (CALLX) (CALLX) (Hex) Operand Program 0283 Operand 2 Argument list 1 be called or Call temto Operand 3 Return list plate Operand 1: Operand 2: Operand Operand 3: Instruction definition System pointer or Space pointer data list or object. null. list or null. Warning: The following information is subject to change from release and be prepared to adjust for changes with each new release. to release. Use it with caution The instruction preserves the calling invocation and passes control to either the program entry procedure of a bound program or the external entry point of a non-bound program. If operand 1 specifies a bound program which does not contain a program entry procedure, an invalid operation for program (hex 2C15) exception is signaled. Description: | | | 1 may be specified as a system pointer which directly addresses the program that is to receive control or as a space pointer to a call template which identifies the program to receive control. Specifying a template allows for additional controls over how the specified program is to be invoked. Operand ! format of the call template is the following: Call options — Char(4) Suppress adopted user profiles = No = Yes 0 1 - Reserved (binary — Force process state to user state for 0) Bits 1-30 call Bit 31 = No = Yes 0 1 Reserved (binary Program BitO 0) Char( 12) to be called System pointer The suppress adopted user profiles call option specifies whether or not the program adopted and propagated user profiles which may be serving as sources of authority to the process are to be suppressed from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit from their authority. Specifying no allows the normal propagation of adopted and propagated user profiles to occur. The called program may adopt the authority available to its invocation. The force process process to user its state to user state option specifies owning user profile, whether or not the if necessary, to supplement call changes the state of the state. Chapter 9. Program Execution Instructions 9-6 Call External Common Program The Call Processing: non-bound and bound pro- details of processing differ for common grams. The following outlines the (CALLX) steps. is made to determine if the caller has authority to invoke the program and that the object indeed a program object. The specified program must be either a bound program that contains is a program entry procedure or a non-bound program. 1. A check 2. The activation group in which the program to be run is located or created is activation group supplies the storage resources required for if it program execution: doesn't exist. The static, automatic, and heap storage. 3. If the program requires an activation entry and vation group, it is require an activation vation 4. is set to 1 it is not already active within the appropriate acti- Bound programs always require an activation; non-bound programs only if they use static storage. The invocation count of a newly created acti- activated. while the invocation count of an existing activation The invocation created for the target program has the following incremented by is attributes (as 1. would be reported via the Materialize Invocation Attributes instruction.) • the invocation process. If mark one higher than the current mark count value maintained is the program was activated as a result of the call then the activation mark, otherwise the invocation the invocation is number is • the invocation type • the invocation • the invocation type is number is is the same Control Normal flow-of-control resume or CALLX invocation. as the invocation number of the transferring invocation. if required, is allocated on a 16-byte boundary. at the instruction following the program call instruction after at the instruction following the caller of the a program issuing the instruction. The details of locating the target model of the program. activation group and activating the Bound Program: A bound program attributes. CALLPGM transferred to the program entry procedure (or external entry point) of the program. Normal flow-of-control resumes return from the program. XCTL This hex 02 to indicate a XCTL type of invocation. 6. is of the calling invocation. call-stack. hex 01 to indicate a The automatic storage frame (ASF), 8. equal will larger than the activation mark. is one greater than the invocation number merely a measure of the depth of the 5. 7. for the mark The so-called mark counts are generated from a counter maintained for the process. Each time a mark is required the counter is incremented. The mark counts thus form a non-decreasing sequence of unique identifiers which can be used to distinguish the time ordering of activations, invocations, and activation groups. Note; • mark invocation its There are two is activated and run in program differ depending upon the an activation group specified by program logical steps involved: • locate the existing, or create a • locate an existing, or create a new new activation group for the activation entry for the program program within the activation group is passed to the program entry procedure for destroyed when the invocation for the program entry After locating the activation entry for the program, control the program. procedure is If required, the activation group is destroyed. Chapter 9. Program Execution Instructions 9-7 Call External ! | | | (CALLX) Non-bound Program: The automatic storage frame begins with a 64 byte header, if the program defines no automatic data items the frame consists solely of the 64-byte header, otherwise the automatic storage items are located immediately following the header. In prior releases of the machine, this header contained invocation information which is now available via the Materialize Invocation (MATINVAT) instruction. This header is not initialized and the contents of the header are not used by the machine. (The space is allocated merely to provide for compatibility with prior implementations of the machine.) The update PASA stack program attribute, supported in prior implementations of the machine, is no longer meaningful and is ignored, if specified as an attribute of the program. Attributes | | | | Following the allocation and initialization of the invocation entry, control is passed to the invoked program. Operand 2 specifies an operand that identifies the arguments to be passed to the invocation entry no arguments are passed by the instruction. A parameter list length (hex 0802) exception is signaled if the number of arguments passed does not correspond to the number required by the parameter iist of the target program. to be called. If operand 2 list is null, _ Operand 3 specifies an IDL (instruction definition list) that identifies the instruction number(s) of alternate return points within the calling invocation. A Return External instruction in an invocation immediately subordinate to the calling invocation can indirectly reference a specific entry in the IDL to cause a return of control to the instruction associated with the referenced IDL entry. If operand 3 is null, then | | | the calling invocation has no alternate return points associated with the call. If operand 3 is not null and operand 1 specifies a bound program, an invalid operation for program (hex 2C15) exception is signaled. Authorization Required a Operational — Program 3 referenced by operand 1 Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 06 01 08 1 space addressing violation 3 Other X 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter 01 parameter reference violation 02 parameter 0A 2 Addressing list X length violation X Authorization 01 unauthorized for operation X Chapter 9. Program Execution Instructions 9-8 Call Internal (CALLI) Operands Exception 10 1 2 3 Other X X X X Damage encountered 04 system object damage state X 05 authority verification terminated due to damaged object 44 1 partial system object damage X 22 24 X limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer 2C X does not exist 02 pointer type invalid X 03 pointer addressing invalid object X Program execution X 15 invalid operation for program 1 X IF program signature violation X 20 static storage overflow X program import X invalid 22 data reference invalid X 23 imported object invalid X 24 activation group export conflict X 25 import not found X Resource control limit X exceeded Space management 01 38 X IE activation access violation 01 user profile storage limit 36 X D automatic storage overflow 21 2E X Machine-dependent exception 03 machine storage 20 X Lock state 01 invalid lock state 1C X X space extension/truncation Template specification X 01 template value invalid Chapter 9. Program Execution Instructions 9-9 Call Internal (CALLI) Call Internal (CALLI) Op Code Operand (Hex) 0293 Operand 2 Argument list 1 Internal entry Operand 3 Return target point Operand 1: Internal entry point. Operand 2: Operand Operand 3: Instruction pointer. list or null. Warning: The following information is subject to change from release to release. Use and be prepared to adjust for changes with each new release. Description: The internal entry point specified by which the Call Internal instruction transferred to the first is executed. A operand is 1 subinvocation located is in is same with caution invocation from defined and execution control instruction associated with the internal entry point. cause a new invocation to be established. Therefore, there in the subinvocation have access to all invocation objects. the it The instruction is does not no allocation of objects and instructions Operand 2 specifies an operand list that identifies the arguments to be passed to the subinvocation. If operand 2 is null, no arguments are passed. After an argument has been passed on a Call Internal instruction, the corresponding parameter may be referenced. This causes an indirect reference to the storage area located by the argument. This mapping exists until the parameter is assigned a new mapping based on a subsequent Call Internal instruction. A reference to an internal parameter before its being assigned an argument mapping causes a parameter reference violation (hex 0801) exception to be signaled. Operand 3 specifies an instruction pointer that identifies the pointer into which the machine places addressability to the instruction immediately following the Call Internal instruction. A branch instruction in the called subinvocation can directly reference this instruction pointer to cause control to be passed back to the instruction immediately following the Call Internal instruction. Exceptions Operands Exception 06 space addressing violation Other X X 03 range X 06 optimized addressability invalid X Argument/parameter parameter reference violation X Damage encountered 04 system object damage state 44 1C 3 02 boundary alignment 01 10 2 Addressing 01 08 1 partial system object damage X X X X X X X X Machine-dependent exception 03 machine storage limit exceeded X Chapter 9. Program Execution Instructions 9-10 Cancel Invocations (CANINV) Operands Exception 20 Machine support 22 1 2 3 02 machine check X 03 function check X Object access X 08 object compressed 24 Pointer specification 01 pointer X does not exist X 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 36 Other X exceeded Space management 01 X space extension/truncation Chapter 9. Program Execution Instructions 9-1 Deactivate Program (DEACTPG) Clear Invocation Exit (CLRIEXIT) Op Code (Hex) 0250 Description: exception The instruction signaled removes the invocation exit program for the requesting invocation. No an invocation exit program is not specified for the current invocation. Also, an implicit clear of the invocation exit occurs when the invocation exit program is given control, or the program which set the invocation exit completes execution. is if Exceptions Exception 10 other Damage encountered 04 System object damage state 44 1C Partial 22 X Machine-dependent exception 03 Machine storage 20 X system object damage limit exceeded X Machine support 02 Machine check X 03 Function check X Object access 08 object compressed 2E Resource control limit 01 user profile storage limit 36 X exceeded X Space management 01 space extension/truncation X Chapter 9. Program Execution Instructions 9-12 Program (DEACTPG) Deactivate Deactivate Program Op Code Operand Program (Hex) 0225 Operand — (DEACTPG) System pointer or 1: 1 null. ILE access DEACTPG ( var program : system pointer or null operand ) This instruction, provided that certain conditions are met, deactivates a non-bound Subsequent invocations of the program within the same activation group will cause a new Description: program. activation to be created. Operand entry is 1 program activation entry which by one of two means: specifies inferred is to be deactivated, if permitted. The activation - the target activation entry is that associated with the current invocation not null - the target activation entry associated with the program system pointer 1. operand 1 is null 2. operand 1 is is selected from one of the two default activation groups The target activation entry signaled is deactivated the deactivation permitted. if is An not permitted. exception is then no operation is performed. If the program specified program (hex 2C15) exception is signaled. if activation in use If is by invocation (hex 2C05) the target activation entry does not exist, a bound program, an invalid operation for general, only those activations with a zero invocation count can be deactivated. In The following two exceptions apply: 1. A program can cation count 2. deactivate must be An invocation exit itself if it is the only invocation of that program in the process (its invo- 1.) program can deactivate the program on whose behalf is no more than 1. it is running provided that the invocation count of that program Authorization Required • Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize - Contexts referenced for address resolution Exceptions invalid operation for program Operand 1 Exception 06 Other Addressing Chapter 9. Program Execution Instructions 9-13 End (END) Operand Exception X 02 boundary alignment X 01 03 range 01 08 X optimized addressability invalid X Argument/parameter parameter reference violation 0A X Authorization unauthorized for operation X Damage encountered 10 04 system object damage state 05 authority verification terminated due to 44 1A X damaged X system object damage partial X object X X Lock state 01 invalid lock state 20 Other 1 01 space addressing violation 06 X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found X 02 object destroyed X 03 object suspended X 07 authority verification terminated due to destroyed object X 08 object compressed 24 X Pointer specification 01 pointer does not exist X 02 pointer type invalid X 03 pointer addressing invalid object 2C X Program execution 05 activation in use by invocation X 15 invalid operation for program 2E Resource control 01 user profile storage limit 32 X limit exceeded X Scalar specification 01 scalar type invalid 36 X Space management 01 space extension/truncation X Chapter 9. Program Execution Instructions 9-14 Materialize Activation Attributes (MATACTAT) End (END) Op Code (Hex) 0260 end of a program's instruction stream. When this instruction to the preceding invocation (if present) or causes termicauses a return is encountered in executed in the highest-level invocation for a process. instruction is the phase if nation of the process stream. When it is encountered in execution, instruction the the end of The End instruction delineates Description: The instruction delimits the execution, it the instruction functions as a Return External instruction with a null operand. External instruction for a description of that instruction. Refer to the Return Exceptions Other Exception 10 Damage encountered 04 system object 44 1C partial damage X state X system object damage Machine-dependent exception 03 machine storage limit exceeded 20 Machine support 02 machine check 03 function check 22 Object access 08 object compressed 2E Resource control limit 01 user profile storage limit 36 exceeded Space management 01 space extension/truncation Chapter 9, Program Execution instructions 9-1 Materialize Activation Attributes Materialize Activation Attributes I | I | | | Op Code (Hex) Operand 0213 (MATACTAT) Operand 1 Receiver (MATACTAT) Operand 7: Operand 2: Binary{4) scalar Operand 3: Character(l) scalar (fixed length) Operand 2 Activation mark 3 Attribute selection Space pointer ILE access 1 MATACTAT ( recei ver space pointer ; unsigned binary, aggregate var activation mark var attribute selection ) | | | I | Warning: The following information is subject to change from release to release. Use and be prepared to adjust for changes with each new release. Description: The operand | | Operand • hex 00 • hex 01 | | I | | | Any value Operand activation provided to deal with the variable-length nature of some of the type information can be gathered by selecting the first option — basic — static for activation attributes storage frame operand 3 list other than those listed 2 supplies the activation will cause a scalar value invalid (hex 3203) exception. mark of the activation for which information is to be returned. The an activation within a process. A value of zero is interpreted to be information about the activation of the invoking program. mark uniquely identifies identified by operand 1 must be 16-byte aligned in the space materialization template has the following format: Template size specification Number I I • | The Bin(4) for materialization Bin(4) Char(8) Returned information Char(*) nMMMMvided user of the instruction. In all This Char(8) of bytes provided for materialization — Number of bytes available — Reserved (binary 0) I | is All “length-of-list” The materialization template • I operand and return the information can have the following values: a request for | I 3 2 with caution materialize the information selected by operand 3 for the program in the template supplied by operand 1. will operand 3 selection returned information. described below. | | This instruction activation specified by it number of bytes provided number of bytes provided is indicates the cases if the for returned information by the less than 8, then a materialization length (hex 3803) exception will be signaled. Chapter 9. Program Execution Instructions 9-1 (MATACTAT) Materialize Activation Attributes The number of bytes available is set by the instruction to indicate the actual number of bytes available | to be returned. In no case does the instruction return more bytes of information than those available. | The format of returned information is described in the following paragraphs. | Basic Activation Attributes: The following information is returned when operand 3 is hex 00. | Aystem pointer Program UBin(4) mark Activation Activation group UBin(4) mark UBin(4) Invocation count Static UBin(4) frame count Char(1) Program model Hex 00 = original model Hex 01 = new model Hex 02-FF = reserved Activation attributes Char(3) — bit — A Activation status 0 = inactive 1 = active Reserved (binary 0 bits 1-23 0) description of the fields follows. program This is The system pointer returned does not contain process, a program may have more than one activation. a pointer to the program. Within a authority. activation mark The activation mark identifies the activation within the process. This field provides the actual activation mark when the special zero value was supplied for operand 2. Otherwise, this field has the same value as operand 2. activation group mark This identifies the activation group which contains the activation. invocation count program invocations which currently exist for this activation of the program. Recall that a program invocation results from a program call operation like Call Program not a procedure call operation like Call Bound Procedure. This static is a count of the number of frame count This is the number of static storage frames allocated for this activation. program model the model of the program. A program is either an original model (non-bound) or new model (bound) program. activation attributes The • activation attributes identify whether the program is active or not. Only original model program can be deactivated by use of the Deactivate Program instruction. Chapter 9, Program Execution Instructions 9-17 Materialize Activation Attributes | (MATACTAT) Frame List: The following information is returned when operand 3 is hex 01. This is a of static storage frame descriptors. The static frame count (available in the basic activation attriûtes template) indicates how many entries must be accommodated by the template. The static stora 9 e frame list can be materialized only if the source activation group is permitted access to the target activation group as determined by the activation group access protection mechanism. If access is not permitted, then an activation group access violation (hex 2C12) exception is signaled. Static Storage list | ! I | | | The format of the • array(1 .. static frame count) of - is Static This — frame base Static This — | list is: Space pointer a pointer to the first byte of the static frame. frame size is the size, UBin(4) in machine dependent units (currently bytes), of the static frame. Reserved Char(12) Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 06 optimized addressability invalid 3 X X X X parameter reference violation X X X X X X X X X X X X X X X Damage encountered 04 system object damage state 05 authority verification terminated due to damaged object 44 1C partial X system object damage X X X 03 machine storage limit exceeded limit X exceeded X 09 auxiliary storage pool number invalid X Machine support 02 machine check x 03 function check 22 X Object access 02 object destroyed 24 X Machine-dependent exception 04 object storage 20 Other Argument/parameter 01 10 2 X 03 range 08 1 Addressing X Pointer specification 01 pointer does not exist X Chapter 9. X X X Program Execution Instructions 9-1 Materialize Activation Group Attributes (MATAGPAT) Operands XXX 1 Exception 02 pointer type invalid X 03 Pointer addressing invalid object 2C 32 2 3 Other X X Program execution 12 Activation group access violation X 16 Activation not found X Scalar specification 03 Scalar value invalid 38 Template specification X 03 Materialization length 44 Domain 01 specification Domain X Violation Chapter 9. Program Execution Instructions 9-1 Materialize Activation I | I Materialize Activation Op Code (Hex) 02D3 Group Operand (MATAGPAT) Attributes Operand 1 Receiver Group Attributes (MATAGPAT) Operand 2 Activation group 3 Attribute selection mark | | | Operand 1: Operand 2: Unsigned binary(4) scalar Operand 3: Character(l) scalar (fixed length) — Space pointer ILE access MATAGPAT ( receiver var acti vati on_group_mark var attri bute_sel ecti on | | | ! space pointer unsigned binary, aggregate : ; : : Warning: The following information is subject to change from release to release. Use and be prepared to adjust for changes with each new release. Description: it with caution This instruction will materialize the information selected by operand 3 for the activation group specified by operand 2 and return the information in the template supplied by operand 1. If the activation group mark specified by operand 2 is zero, then information about the activation group associated with the current invocation is returned. order to deal with the variable-length nature of some activation group attributes, the selection option All of the “length-of-list” type information can be gathered by selecting the first option described below. 'n is provided. Operand 3 0 hex 00 * hex 01 • hex 02 Any value can have the following values: — basic activation group — activation group heap — program activation attributes list list for operand 3 other than The materialization template option option those identified cause a scalar value invalid (hex 3203) exception. listed will by operand 1 must be 16-byte aligned in the space. This materialization template has the following format: Materialization size specification — Number of bytes — Number of bytes Reserved (binary Char(8) provided for materialization Bin(4) available for materialization Bin(4) 0) Char(8) Returned information The nu mber Char(*) of bytes provided indicates the the user of the instruction. In all cases if number of bytes provided for returned information by number of bytes provided is less than 8, then a the materialization length (hex 3803) exception will be signaled. Chapter 9. Program Execution Instructions 9-20 Materialize Activation The number of bvtes available able to be returned. Group Attributes (MATAGPAT) set by the instruction to indicate the actual is number of bytes avail- no case does the instruction return more bytes of information than those In available. The format of returned information Basic Activation Group Attributes: is described in the following paragraphs. The following information is returned when operand Root program • Reserved (binary • Storage address recycling key • Activation group • Reserved (binary • Activation group • Reserved (binary « Heap space count UBin(4) • Activation count UBin(4) • Static storage size UBin(4) • Automatic storage size UBin(4) 9 Attributes Char(1) — Reserved Bit 0 - Activation group state. Bit 1 1 - Is 0 1 - = = 1 = = System pointer or Char(2) 0) UBin(4) mark Char(4) 0) Bit 2 group named? no yes Bit 3 no yes Bits 4-7 (binary 0) Char(1) — Bit 0 Automatic storage 1 - 1 in permit creation PAG PAG in Bit = = do not create in permit creation 1 = = do not create in permit creation Reserved (binary 1 PAG PAG in Bit 2 Default heap storage 0 — do not create Static storage 0 - = = null Char(30) name Process access group membership advisory attributes 0 null user — Reserved • 00. Char(16) 0) Destroy pending? 0 hex system activation = = is System pointer or • 0 3 PAG PAG in Bits 3-7 0) Additional Description Chapter 9. Program Execution Instructions 9-21 Materialize Activation root I storage address recycling kev a system pointer I I wise the I activation I returned only is if the activation group state is specified as user other- field is null. group name For activation groups which do not have a symbolic name, this I field contains all blanks. heap space count is the number of heap spaces currently associated with the activation group. is the number of programs which are currently is the maximum amount This I activation count This I I (MATAGPAT) those activation groups which are created by the machine (the default activation groups) do not have root programs, in which case this field is null. I | Attributes program | | Group active within the activation group. static storage size This i I been allocated | essarily reflect the of static storage, to the activation amount group at in machine dependent units, which has any particular time. Note that this does not nec- of storage currently in use. automatic storage size is the maximum amount of automatic storage, in machine dependent units, which has been allocated to the activation group at any particular time. Note that this does not necessarily reflect the amount of storage currently in use. It is merely a measure of the maximum “depth” the automatic storage stack has had to this point. This is group named? Indicates whether the activation group is named or unnamed. The activation group name field contains blanks for unnamed an activation groups. The default activation groups and activation those created with the “unnamed” attribute are unnamed. Group Heap List: When operand 3 is hex 01, the format of the returned information is an array of heap identifiers. This is a list of the heaps which are currently associated with the activation group. The heap space count (available in the basic template) Activation indicates accommodated by » the template. The format of the a rray(1 .. heap space count) of Information about a specific heap (MATHSAT) how many entries must be list is: Bin(4) may be obtained from the Materialize Heap Space Attributes instruction. Program Activation When operand 3 is hex 02, the format of the returned information is an array Each activation mark represents a program activation within the activation group, (The activation mark is a number which uniquely identifies the activation within a process.) The activation count (available in the basic template) indicates how many entries must be accommodated by List: of activation marks. i \ | the template. • | | The format of the list is: array(1. activation count) of Information about a specific activation | (MATACTAT) | Exceptions UBin(4) may be obtained from the Materialize Activation Attributes instruction. 12 Operands Exception | | | 06 Addressing 01 3 Other XXX space addressing violation Chapter 9. Program Execution Instructions 9-22 Modify Automatic Storage Allocation (MODASA) Operands XXX XXX XXX Exception 02 boundary alignment 03 range 06 optimized addressability invalid 08 parameter reference violation X X X X X X damage state 05 authority verification terminated due to 44 partial damaged X object X system object damage 04 object storage limit limit X exceeded X Machine support 02 machine check X 03 function check X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X X X 03 Pointer addressing invalid object 32 X X exceeded 09 auxiliary storage pool number invalid 24 X Machine-dependent exception 03 machine storage 20 3 Damage encountered 04 system object 1C 2 Argument/parameter 01 10 Other 1 Scalar specification 03 Scalar value invalid 2C Program execution X 13 Activation group not found 38 Template specification X 03 Materialization length 44 Domain 01 specification Domain X Violation Chapter 9. Program Execution Instructions 9-23 Modify Automatic Storage Allocation (MODASA) Modify Automatic Storage Allocation Op Code (Hex) Operand 02F2 /: Operand 2: MODASA | I : ) | null. Signed binary scalar. — ( modification_size ! 2 Modification size Space pointer data object or ILE access I Operand 1 Storage allocation Operand (MODASA) signed binary, OR unsigned binary, space pointer /* storage_al location */ : Description: The automatic storage frame (ASF) of the current invocation the size specified by operand 2. A positive value indicates that the frame value indicates that the frame is to be truncated a zero value does not not null, • • it will extended or truncated by to be extended a negative ; change the ASF. ; is is is operand 1 be treated as follows: ASF extension: receives the address of the first byte of the extension. The be contiguous with the remainder of the ASF allocation. ASF If truncation: Operand ASF extension might not should be null for truncation. If operand 1 is not null, then addressablity space is returned. This value should not be used as a space locates space that has been deallocated. 1 to the first byte of the deallocated pointer since • lf When it a value of ze ro the ASF is is specified for operand extended, the extension is 2: the value returned is unpredictable. aligned on a 16-byte boundary. An extension is not initialized. A scalar value invalid (hex 3203) exception to be less than the A space pointer amount of the initial is signaled if truncation amount would cause size of the ASF allocation. machine object cannot be specified for operand 1. Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 08 2 X X X X 03 range X X 06 optimized addressability invalid X X Other X X Argument/parameter 01 10 1 Addressing parameter reference violation Damage encountered 04 system object 44 partial damage XXX XXX state system object damage Chapter 9. Program Execution Instructions 9-24 Return External (RTX) Operands 1 Exception 1C 03 machine storage 20 22 24 2 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X X X X X Pointer specification 01 pointer does not exist 02 pointer type invalid X 08 object compressed 2C Program execution 1 2E X D automatic storage exceeded Resource control limit 01 user profile storage limit 32 Other Machine-dependent exception X exceeded Scalar specification X 01 scalar type invalid X 02 scalar attributes invalid X 03 scalar value invalid X Chapter 9. Program Execution Instructions 9-25 Return External (RTX) Return External (RTX) Op Code (Hex) Operand 02A1 1 Return point Operand /: Signed binary (2) scalar or null. Description: The instruction terminates execution of the invocation The automatic storage frame is deallocated. tied. | A in which the instruction is speci- Return External instruction can be specified within an invocation's subinvocation, and no exception is signaled. If a higher invocation exists the preceding invocation in in the invocation hierarchy, the instruction causes execution to resume in the process' invocation hierarchy at an instruction location indirectly speciby operand 1. If operand 1 is binary 0 or null, the next instruction following the Call External which control was relinquished in the preceding invocation in the hierarchy is given execution control. If the value of operand 1 is not 0, the value represents an index into the instruction fied instruction from definition (IDL) specified as the return list operand in the Call External instruction, and the value be passed to the instruction referenced by the corresponding IDL entry. The first IDL referenced by a value of one. If operand 1 is not 0 and no return list was specified in the list causes control entry is to Call External instruction, or value is the value of operand 1 exceeds the negative, a return point invalid (hex 2C02) exception if number is of entries in the IDL, or if the signaled. If a higher invocation does not exist, the Return External instruction causes termination of the current process state. If operand 1 is not 0 and is not null, the return point invalid (hex 2C02) exception is signaled. Refer to the Terminate Process instruction for the functions performed in process termination. the returning invocation has received control to process an event, then control is returned to the where the event handler was invoked. In this case, if operand 1 is not 0 and is not null then a return point invalid (hex 2C02) exception is signaled. If point If the returning invocation has received control from the machine to process an exception, the return is signaled. instruction invalid (hex 2C02) exception If If the returning invocation has an activation, the invocation count in the activation the returning invocation currently has an invocation exit set, the invocation exit is implicitly cleared. is is decremented by 1 not given control and Exceptions Operand Exception 1 06 01 space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid 08 Other Addressing X Argument/parameter 01 parameter reference violation X Chapter 9. Program Execution Instructions 9-26 Set Argument List Length (SETALLEN) Operand Exception 10 04 system object 44 1C partial damage 22 state system object damage Other X X X X Machine-dependent exception 03 machine storage 20 1 Damage encountered limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C X X X X Program execution X 01 return instruction invalid X 02 return point invalid 2E Resource control limit 01 user profile storage limit 36 X X exceeded Space management 01 X space extension/truncation Chapter 9. Program Execution Instructions 9-27 Set Argument List Length (SETALLEN) Set Argument List Length (SETALLEN) Op Code Operand 1 Argument list (Hex) 0242 Operand 1: Operand 2: Operand Operand 2 Length list. Binary scalar. Description This instruction specifies the number of arguments to be passed on a succeeding Call External or Transfer Control instruction. The current length of the variable-length operand list (used as an argument list) specified by operand 1 is modified to the value indicated in the binary scalar specified by operand 2. This length value specifies the number of arguments (starting from the first) to be passed from the list when the operand list is referenced on a Call External or Transfer Control instruction.; Only variable-length operand with the lists argument list attribute may be modified by the instruction. The value in operand size specified in the may range from 2 ODT 0 (meaning no arguments are to be passed) to the definition of the operand list (meaning all maximum defined arguments are to be passed). The length of the argument list remains in effect for the duration of the current invocation or Argument List Length instruction is issued against this operand list. until a Set Exceptions Operands Exception 06 01 08 1 space addressing violation X 03 range X 06 optimized addressability invalid X Argument/parameter parameter reference violation 03 argument list X length modification violation X Damage encountered XXX XXX 04 system object damage state 44 1C partial system object damage Machine-dependent exception 03 machine storage 20 limit exceeded X Machine support 02 machine check X 03 function check 22 Other X 02 boundary alignment 01 10 2 Addressing X Object access found X 02 object destroyed X 01 object not Chapter 9. Program Execution Instructions 9-28 Set Invocation Exit (SETIEXIT) Operands Exception 03 object suspended 1 2 X 08 object compressed 24 Pointer specification 01 pointer does not X exist X 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification X 03 scalar value invalid 36 Other X Space management 01 X space extension/truncation Chapter 9. Program Execution Instructions 9-29 Set Invocation Exit (SETIEXIT) Set Invocation Exit (SETIEXIT) Op Code Operand (Hex) 0252 1 Invocation exit Operand 2 Argument list program Operand 1: System pointer Operand 2: Operand list or null Description: This instruction allows the external entry point of the program specified by operand 1 to be given control when the requesting invocation is destroyed due to normal exception handling actions, or due to any process termination. Normal exception handling actions are considered to be those actions performed by the Return From Exception (RTNEXCP) or the Signal Exception (SIGEXCP) instructions. Operand 1 is a system pointer addressing the program that is to receive control. The operand 1 system pointer must be in either the static or automatic storage of the program invoking this instruction. Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation program being called. If operand 2 is null, no arguments are passed to the invocation. No operand exit when this instruction is executed. Nor are copies made of the operand values after execution of this instruction will be used Operand verification occurs on the original form of the operands verification takes place operands, so changes made to the during later operand verification. when the invocation exit program is invoked. At that time operational authorization to the invocation program and retrieve authorization to any contexts referenced for materialization take place. Also, materialization lock enforcement occurs to contexts referenced for materialization. exit | an invocation If exception tion exit is program currently exists for the requesting invocation, it is replaced, and no The invocation exit set by this instruction is implicitly cleared when the invocagiven control, or the program which set the invocation exit completes execution. exit signaled. program is any invocations are to be destroyed due to normal exception handling actions, then those invocation programs associated with the invocations to be destroyed are given control before execution proceeds to the signaled exception handler. If exit A failure to invoke program (hex 0011,04,01) event is signaled when both of the following conditions occur: management is destroying an invocation stack due to a Signal Exception instruction, a Return From Exception instruction, or process termination. • Exception » An invocation exit program From Exception instruction. is to be destroyed due to a second Signal Exception or a second Return The invocation exit program that is being destroyed is terminated, and its associated invocation exeterminated. Termination of invocations due to a previous Signal Exception instruction, a Return From Exception instruction, or a process termination is then resumed. cution is a process phase terminated and the process was not in termination phase, then the invocations Invocation exit programs set for the terminated invocations are allowed to run. If an invocation to be terminated is an invocation exit program, then the following occurs: If is are terminated. • A failure to • If an invocation invoke program (hex 0011,04,01) event exit has been set for is signaled. this invocation exit, it is allowed to run. Chapter 9. Program Execution Instructions 9-30 Store Parameter List Length (STPLLEN) 9 The invocation exit is terminated and the associated invocation is terminated (the invocation exit is not reinvoked). Invocation exit programs for the remaining invocations to be terminated are then allowed to run. Exceptions Operands Exception 06 1 01 ! L— Other Addressing X space addressing violation i 08 2 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter 01 X parameter reference violation j 10 Damage encountered 04 system object damage state 44 1C partial 22 X system object damage Machine-dependent exception 03 machine storage 20 X limit X exceeded Machine support 02 machine check X 03 function check X Object access X 08 object compressed 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification X 01 scalar type invalid 36 Space management 01 X space extension/truncation Chapter 9, Program Execution Instructions 9-31 Store Parameter List Length (STPLLEN) Store Parameter List Length (STPLLEN) Op Code Operand (Hex) 0241 1 Length Operand 1: Binary variable scalar. A value is returned in operand 1 that represents the number of parameters associated with the invocation's external entry point for which arguments have been passed on the preceding Call External or Transfer Control instruction. Description: The value can range from 0 (no parameters were received) parameter list associated with the external entry point. to the maximum size possible for the Exceptions Operand Exception 06 space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter 01 parameter reference violation 10 X Damage encountered 04 system object damage state 44 1C partial system object damage 22 X X X X Machine-dependent exception 03 machine storage 20 limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X 08 object compressed 24 X Pointer specification 01 pointer does not exist X 02 pointer type invalid 2E Resource control X limit 01 user profile storage limit 32 Other Addressing 01 08 1 exceeded X Scalar specification Chapter 9. Program Execution Instructions 9-32 Transfer Control (XCTL) Operand Exception 36 1 01 scalar type invalid X 02 scalar attributes invalid X Other Space management 01 X space extension/truncation Chapter 9. Program Execution Instructions 9-33 Transfer Control (XCTL) Transfer Control (XCTL) Op Code Operand Program (Hex) 0282 1 be called or Call temto Operand 2 Argument list plate | | Operand 1: Operand 2: Operand The Description: list or null. and passes control to either the program program or the external entry point of a non-bound program. If operand 1 a bound program that does not contain a program entry procedure, an invalid operation for instruction destroys the calling invocation entry procedure of a bound specifies | | System pointer or Space pointer Data Object. program (hex 2C15) exception is signaled. 1 may be specified as a system pointer which directly addresses the program that is to receive control or as a space pointer to a call template which identifies the program to receive control. Specifying a template allows for additional controls over how the specified program is to be invoked. Operand The format of the call template is the following: Call options - Suppress 0 1 = = Char(4) adopted user profiles no yes — Reserved (binary 0) - Force program state 0 1 = = Bit 1-30 to user state for transfer Bit 31 no yes Reserved (binary Program Bit 0 Char(12) 0) to be called System Pointer The suppress adopted user profiles option specifies whether or not the program adopted and propagated user profiles which may be serving as sources of authority to the process are to be suppressed from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit from their authority. Specifying no allows the normal propagation of adopted and propagated user profiles to occur. The called program may adopt its owning user profile, if necessary, to supplement the authority available to its invocation. The force program state to user state for transfer option specifies whether or not the transfer control needs to be done in the current program state or as though the transfering program were running in the user state without the transferring program changing to run in the user state. If | | | the transferring invocation has an activation, the invocation count Common Program Call Processing: The details of processing grams. The following outlines the common steps. 1. | decremented by differ for 1. non-bound and bound pro- is made to determine if the caller has authority to invoke the program and that the object indeed a program object. The specified program must be either a bound program that contains A check is | a | is program entry procedure or a non-bound program. Chapter 9. Program Execution Instructions 9-34 Transfer Control (XCTL) Operand Exception 36 1 01 scalar type invalid X 02 scalar attributes invalid X Other Space management 01 X space extension/truncation Chapter 9. Program Execution Instructions 9-33 Transfer Control (XCTL) Transfer Control (XCTL) Op Code Operand Program (Hex) 0282 1 be called or Call temto Operand 2 Argument list plate | | | | Operand 1: Operand 2: System pointer or Space pointer Data Object. Operand list or null. The instruction destroys the calling invocation and passes control to either the program entry procedure of a bound program or the external entry point of a non-bound program. If operand 1 specifies a bound program that does not contain a program entry procedure, an invalid operation for Description: program (hex 2C15) exception is signaled. 1 may be specified as a system pointer which directly addresses the program that is to receive control or as a space pointer to a call template which identifies the program to receive control. Specifying a template allows for additional controls over how the specified program is to be invoked. Operand The format of the call template is the following: Call options — Char(4) Suppress adopted user 0 1 = = 1 = = no Bit 1-30 to user state for transfer Bit 31 no yes Reserved (binary Program Bit 0 yes - Reserved (binary 0) — Force program state 0 profiles Char(12) 0) to be called System Pointer The suppress adopted user profiles option specifies whether or not the program adopted and propagated user profiles which may be serving as sources of authority to the process are to be suppressed from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit from their authority. Specifying no allows the normal propagation of adopted and propagated user profiles to occur, The called program may adopt its owning user profile, if necessary, to supplement the authority available to its invocation. The force program state to user state for transfer option specifies whether or not the transfer control needs to be done in the current program state or as though the transfering program were running in the user state without the transferring program changing to run in the user state. If | | | the transferring invocation has an activation, the invocation count Common Program Call Processing: The details of processing grams. The following outlines the common steps. 1. | | | is decremented by differ for 1. non-bound and bound pro- A check is made to determine if the caller has authority to invoke the program and that the object indeed a program object. The specified program must be either a bound program that contains a program entry procedure or a non-bound program. is Chapter 9. Program Execution Instructions 9-34 Transfer Control (XCTL) 2. The activation group in which the program is to be run is located or created activation group supplies the storage resources required for if it program execution: doesn't static, The exist. automatic, and heap storage. 3. If the program requires an activation entry and vation group, it is require an activation vation 4. is set to 1 it is not already active within the appropriate acti- Bound programs always require an activation; non-bound programs only if they use static storage. The invocation count of a newly created acti- activated. while the invocation count of an existing activation The invocation created for the target program has the following is incremented by attributes (as 1. would be reported via the Materialize Invocation Attributes instruction.) • the invocation process. If mark one higher than the current mark count value maintained is the program was activated as a result of the call then the activation mark, otherwise the invocation number • the invocation • the invocation type is is the same The automatic storage frame (ASF), 6. Control is will equal larger than the activation mark. is as the invocation number of the transferring invocation. if required, is allocated on a 16-byte boundary. transferred to the program entry procedure (or external entry point) of the program. Normal flow-of-control resume at the instruction following the caller of the program issuing the instruction. The details of locating the target model of the program. activation Bound Program: A bound program attributes. for the mark hex 02 to indicate a XCTL type of invocation. 5. XCTL invocation The so-called mark counts are generated from a counter maintained for the process. Each time a mark is required the counter is incremented. The mark counts thus form a non-decreasing sequence of unique identifiers which can be used to distinguish the time ordering of activations, invocations, and activation groups. Note: 7. mark its There are two is group and activating the program activated and run in differ depending upon the an activation group specified by program logical steps involved: • locate the existing, or create a • locate an existing, or create a new new activation group for the activation entry for the program program within the activation group After locating the activation entry for the program, control the program. procedure is If required, the activation group is is passed to the program entry procedure for destroyed when the invocation for the program entry destroyed. Non-bound Program: The automatic storage frame begins with a 64 byte header, if the program defines no automatic data items the frame consists solely of the 64-byte header, otherwise the automatic storage items are located immediately following the header. In prior releases of the machine, header contained invocation information which is now available via the Materialize Invocation this (MATINVAT) instruction. This header is not initialized and the contents of the header are not used by the machine. (The space is allocated merely to provide for compatibility with prior implementations of the machine.) The update PASA stack program attribute, supported in prior implementations of the machine, is no longer meaningful and is ignored, if specified as an attribute of the program. Attributes Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation to which control is being transferred. Automatic objects allocated by the transferring invocation are destroyed as a result of the transfer operation and, therefore, cannot be passed as arguments. A parameter list length (hex 0802) exception is signaled if the number of arguments passed does not correspond to the number required by the parameter list of the target program. Chapter 9. Program Execution Instructions 9-35 Transfer Control (XCTL) the transferring invocation has received control to process an exception, or an invocation If return instruction invalid (hex 2C01) exception is the transferring invocation currently has an invocation exit set, the invocation exit is implicitly cleared. If exit, the signaled. is not given control and Authorization Required • Operand — • 1 Operational Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Exception01 06 Addressing 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 parameter reference violation 02 parameter 0A list length violation Authorization unauthorized for operation 10 Damage encountered 04 system object damage state 05 authority verification terminated due to 44 1A partial damaged object system object damage Lock state 01 invalid lock state 1C Machine-dependent exception 02 program limitation exceeded 03 machine storage limit exceeded 20 Machine support 02 machine check 03 function check 22 Object access Chapter 9. Program Execution Instructions 9-36 Transfer Control (XCTL) Operands Exception 24 1 01 object not found X 02 object destroyed X 03 object suspended X X 08 object compressed X Pointer specification does not X exist 02 pointer type invalid X 03 pointer addressing invalid object X Program execution X 01 return instruction invalid X 15 invalid operation for program 1 X D automatic storage overflow IE activation access violation X IF program signature violation X 20 static storage overflow X 21 program import X invalid 22 data reference invalid X 23 imported object invalid X 24 activation group export X conflict X 25 import not found 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 38 Other 07 authority verification terminated due to destroyed object 01 pointer 2C 2 X space extension/truncation Template specification 01 X template value invalid Chapter 9. Program Execution Instructions 9-37 Program Creation Control Chapter 10 . Program Creation Control This chapter describes all A, “Instruction Instructions the instructions used to control the create program function. These instructions are arranged in alphabetic order. Appendix Instructions For an alphabetic summary of all the instructions, see Summary.” No Operation (NOOP) No Operation and Skip (NOOPS) Override Program Attributes (OVRPGATR) 10-4 © 1 Copyright IBM Corp. 1991, 1993 10-3 10-5 0-1 Program Creation Control Chapter 10. Instructions Program Creation Control Instructions 10-2 No Operation (NOOP) No Operation (NOOP) Op Code (Hex) 0000 Description: No function is performed. The instruction consists of an operation code and no oper- may not be branched to and is not counted as an instruction in the instruction The instruction may be used for inserting gaps in the instruction stream. These gaps allow ands. The instruction stream. instructions with adjacent instruction The instruction number of may precede No Operation addresses to be physically separated. or follow any machine instruction except the End instruction, and any instructions may exist in succession. Chapter 10. Program Creation Control Instructions 10-3 No Operation and Skip (NOOPS) No Operation and Skip (NOOPS) Op Code Operand (Hex) 0001 1 Skip count Operand Unsigned immediate value. 1: Description: This instruction performs no function other than to indicate a specific number of bytes within the instruction stream that are to be skipped during encapsulation. It consists of an operation code and 1 operand. Operand 1 is an unsigned immediate value that contains the number of bytes between this instruction and the next instruction to be processed. These bytes are skipped during the encapsulation of this program. A value of zero for operand 1 indicates that no bytes are to be skipped between this instruction and the next instruction to be processed. If the operand 1 skip count indicates that the next instruction to process instruction stream, an invalid operand value range exception is beyond the end of the signaled. is may be used to insert gaps in the instruction stream in such a instructions with adjacent instruction addresses to not be physically adjacent. This instruction This instruction The instruction number Note: not be branched may precede to, and is not counted as an instruction in that allows the instruction stream. or follow any machine instruction except the End instruction, and any instructions may exist in succession. No Operation and Skip of When used in an existing program template, the following items within the adversely affected: this instruction is template • may manner may be The actual count of instructions may be altered to be is specified in the program template header. different than the count of instructions that • Object definitions that reference instructions the intended instruction. may now be out of range or may not reference The actual number of bytes skipped includes the bytes containing the instruction plus the number bytes specified by the skip count value. The number of bytes skipped per template version is as of follows: • Version 0 • Version = 4 plus the skip count value. 1=5 plus the skip count value. Chapter 10 . Program Creation Control Instructions 10-4 Override Program Attributes Op Code Operand (Hex) Operand 1 2 Attribute modifier Attribute identifi- 0006 (OVRPGATR) cation Operand /: Unsigned immediate value. Operand 2: Unsigned immediate value. Description: This program creation control instruction allows one of a set of program attributes speci- below to be overridden. The overridden program attribute is in effect until it is changed by another OVRPGATR instruction. The initial program attributes are set to the ones given in the program template for the Create Program (CRTPG) instruction. These same initial program attributes are the fied ones that are materialized instruction has no when a Material Program on the materialized effect (MATPG) is done. That is, the OVRPGATR attributes. code and two operands. Operand 1 is an unsigned immediate value that contains a representation of which program attribute is to be overridden. Operand 2 is an unsigned immediate value that contains a representation of how the program The OVRPGATR attribute is instruction consists of an operation to be overridden. This instruction may The may precede instruction The program not be branched to, and is operand is 1 Attribute Attribute Identification Description 1 Array constrainment attribute Allowed values = the instruction stream. for operand overridden according to the following selection values: 2: Constrain array references 3 = Do not constrain array references = Fully unconstrain array references 4 = 2 in or follow any machine instruction. attributes defined by 1 not counted as an instruction Terminate override of array constrainment attributes and resume use of the in the program template attributes specified 2 String constrainment attribute Allowed values 1 2 3 = for operand Constrain string references = Do not constrain string references = Terminate override of string constrainment attribute specified in 3 2: Suppress binary size exception Allowed values 1 2 3 for = Suppress operand attribute and resume use of the the program template attribute 2: binary size exceptions = Do not suppress binary size exceptions = Terminate override of suppression of binary resume use of the attribute specified in Chapter size exception attribute and the program template 10. Program Creation Control Instructions 10-5 Override Program Attributes (OVRPGATR) 4 Suppress decimal data exception Allowed values operand for 1 = Suppress 2 = Do 3 = attribute 2: decimal data exceptions not suppress decimal data exceptions Terminate override of suppression of decimal data exception attribute and of the attribute specified in the program template resume use 5 Copy Bytes with Pointers Allowed values 6 1 = 2 = Do for Constrain Compare (CPYBWP) alignment data check operand 2: CPYBWP to require like alignment of not constrain CPWBWPto require Pointer for Space Addressibility Allowed values 1 = 2 = Do for operand like attribute operands (default) alignment of operands (CMPPSPAD) null pointer tolerance attribute 2: Signal pointer does not exist exceptions for operands not signal pointer does not exist exceptions for Chapter 10. 1 and 2 operands 1 (default) and 2 Program Creation Control Instructions 10-6 Independent Index Instructions Chapter 11. Independent Index Instructions These instructions are in alphabetic order. This chapter describes the instructions used for indexes. A, “Instruction Summary.” Appendix For an alphabetic summary of all the instructions, see 11-3 Create Independent Index (CRTINX) Destroy Independent Index (DESINX) Find Independent Index Entry (FNDINXEN) Insert Independent Index Entry (INSINXEN) Materialize Independent Index Attributes Modify Independent Index (MODINX) Remove Independent © 11-12 11-16 (MATINXAT) Index Entry (RMVINXEN) Copyright IBM Corp. 1991, 1993 11-10 11-19 11-23 11-26 . . . . 11-1 Independent Index Instructions i Chapter 11 . Independent Index Instructions 11=2 Create Independent Index (CRTINX) Create Independent Index (CRTINX) Op Code Operand (Hex) 1 0446 Operand 2 Index description Index template Operand 7: System Operand 2. Space pointer. pointer. ILE access CRTINX ( var index description_teniplate : : system pointer-, space pointer ) template specified by This instruction creates an independent index based on the index addressing object the stored in pointer operand 2 and returns addressability to the index in a system Description: specified by operand 1. The format of the index description template described by operand 2 is as follows (must be aligned on a 16-byte multiple): • • » Char(8) Template size specification - Number of bytes provided for materialization Bin(4)* - Number of bytes available for materialization Bin(4)‘ Char(32) Object identification - Object type Char(1)* - Object subtype Char(1) — Object Char(30) name Object creation options Char(4) — Bit 0 Existence attributes 0 1 = = Temporary Permanent - Space attribute 0 = Fixed-length 1 = Variable-length Bit - Bit 2 Initial 0 1 - context = Do not insert addressability in context = Insert addressability in context 1 = Do not = Create - Reserved — Bit 3 Access group 0 Initialize 0 1 = member of access group member of access group create as as Bits 4-12 (binary 0) Bit 13 space Initialize Chapter 11. Independent Index Instructions 11-3 Create Independent Index (CRTINX) = Do 1 not initialize - Reserved (binary 0) Bits 14-31 Recovery options • - Char(4) Reserved (binary 0) Char(2) - ASP number Char(2) • Size of space • Initial • Performance class Bin(4) value of space ~ Space Char(1) Char(4) alignment Bit 0 Pa e associated with the ob ect is allocated to allow proper ° alignment of pointers at ? -iI K f 6 -byte alignments within the space. If no space is specified for the object, 0 must be specK ified for the performance class. = 1 h ass °' iated with the ob ect is all °cated to allow proper alignment of pointers h 6 a W thm the SpaCe 3S Wel1 as to allow proper al '9 n ment of input/output at huff! at 512-byte alignments buffers within the the space. h J ^ , ?“ Reserved (binary J ' 0) Bits 1-4 Main storage pool selection Bit 5 = Process default main storage pool is used for object. = Machine default main storage pool is used for object. 0 1 Reserved (binary 0) Bit 6 Block transfer on implicit access state modification 0 1 = - Bit 7 Transfer the minimum storage transfer size for this object. This value is 1 storage unit Transfer the machine default storage transfer size. This value is 8 storage units. - Reserved (binary 0) Reserved (binary Bits 8-31 0) Char(3) Extension offset Bin(4) Context System pointer Access group System pointer Index attributes Char(1) - Entry length attribute 0 1 — = = Bit 0 Fixed-length entries Variable-length entries Immediate update 0 1 Bit 1 = No immediate update = Immediate update — Key insertion Bit 2 0 1 - = No insertion by key = Insertion by key Entry format Bit 3 0 1 — = = Scalar data only Both pointers and scalar data Optimized processing mode Bit 4 Chapter 11 . Independent Index Instructions 11-4 Create Independent Index (CRTINX) 0 1 = = Optimize Optimize for random references for sequential references — Maximum entry length 0 = Maximum entry length 1 = Maximum entry length — Reserved (binary Bit 5 120 bytes 2000 bytes is is Bits 6-7 0) • Argument length Bin(2) • Key length Bin(2) asterisk This instruction ignores the values associated with the entries annotated with an Note: The template identified by in 2 ). must be 16-byte aligned. located by the extension offset field. The template extension must be the space. The following is the format of the template extension: The template extension 16-byte aligned operand ( is Char(20) • Reserved (binary 0) • Domain assigned to the object • Reserved (binary 0) Char{2) Char(42) permanent, it is owned by the user profile governing process execution. The The storage occuowning user profile is implicitly assigned all private authority states for the object. created object is temporary, pied by the created object is charged to this owning user profile. If the public. Storage occupied by as assigned are states authority there is no owning user profile, and all If the created object the created context The object is is charged to the creating process. identification specifies the symbolic name that identifies the space within the machine. An identification is used to identify object type of hex 0E is implicitly supplied by the machine. The object a context that addresses the object in the locate to as well the object on materialize instructions as object. temporary object. The existence attribute specifies that the index is to be created as a permanent or a machine when the destroyed by implicitly is user, the by destroyed A temporary index, if not explicitly machine processing is terminated. with the created object. The space may be fixed or variable in size, as the size of space field. specified by the space attribute field. The initial allocation is as specified in allocated is dependent on size actual The specified. size the least machine allocates a space of at A space may be associated The an algorithm defined by a specific implementation. field indicates that addressability is to be inserted in a context, that identifies a context where addressability to the newly pointer system the context field must be a context indicates that addressability is not to be placed in a initial created object is to be placed. If the If the initial context creation attribute context, the context field is ignored. group, field indicates that the object is to be created in an access is object the which group in access an identifies that pointer system the access group field must be a the of attribute existence to the identical be must object the to be created. The existence attribute of group field is ignored. access group. If the object is not to be created in the access group, the access If the access group creation attribute space creation option controls whether or not the space is to be initialized. When initialize to a value specified by the initial value of space field. is specified, each byte of the space is initialized this byte value is also used to initialize the new allosize, in Additionally, when the space is extended value of space field is ignored and the initial value initial the cation. When do not initialize is specified, of the bytes of the space are unpredictable. The initialize Chapter 11. Independent Index Instructions 11-5 Create Independent Index (CRTINX) When do not initialize is specified for a space, internal machine algorithms do ensure that any storaqe resources last used for allocations to another object which are reused to satisfy allocations for the space are reset to a machine default value to avoid possible access of data which may have been stored in the other object. To the contrary, reusage of storage areas previously used by the space object are not reset, thereby exposing subsequent reallocations of those storage areas within the space to access of the data which was previously stored within them. The MEjmmber attribute specifies the ASP number of the ASP on which the unit is to be allocated value of 0 indicates an ASP number is not specified and results in the default of allocating the object the system ASP. Allocation on the system ASP can only be done implicitly by not specifying an ASP number. The only nonzero values allowed are 2 through 16 which provide for explicit allocation of Th 6 ASP nUmb6r mUSt Spedfy 3n 6XiSting ASP The ASP number attribute onlvlne t only be specified for creation of a permanent object. The ASP number attribute of an object can be materialized, but cannot be modified. * (h expert The preferred ation be ASP nUmber attribute results êx^ may unit number not be specified m A in the signaling of the template value invalid which can be specified in the performance class field at object creconjunction with specification of the ASP number attribute. attribute in The p erformance class parameter provides information allowing the machine to more effectively manage the object considering the overall performance objectives of operations involving the index. |f the er^Jength attribute field specifies fixed-length entries the entry length of every index entry is of the index description template If entries then entries will be variable-length (the inserted), and the argument length field is ignored. , established at creation by the value in the argument length he entry length attribute field specifies variable-length field , length of each entry If is supplied when the entry is the immediate update field specifies that an immediate update should occur, then every update to the will be written to auxiliary storage after every insert or remove operation. index If the kg yj nsertion field specifies insertion by key then the key length field must be specified. This allows the specification of a portion of the argument (the key), which may be manipulated in either of the following ways in the Insert Index Entry instruction: , The insert will not take place 15 ^ if the key portion of the argument Wl " C3USe the n ° nkey portion of the argument already is to be replaced index The en|ry forma t if in the index. the key is already in the designates the index entries as containing both pointers and scalar data or he b ° th P ° interS and SCa ' ar data field Can be used on| y '/ for inde >< es V fixed-length 9 entries. Iffth the index is created to contain both pointers and data, then field ZtZ • Entries to be inserted must be 16-byte aligned. Each entry retrieved by the Find Independent Index Entry instruction or the Remove Independent Index Entry is 16-byte aligned. Pointers are allowed in both the key and nonkey portions of an index entry. Pointers need not be at the same location every index entry. in Pointers inserted into the index remain unchanged. If the index is No resolution is performed before insertion. created to contain scalar data only then: , * Entries to be inserted need not be aligned. Entnes returned by the Find Independent index Entry instruction or the Entry instruction are not aligned. Chapter 11 . Remove Independent Independent Index Instructions Index 11-6 Create Independent Index (CRTINX) Any pointers inserted . into the index will be invalidated. index should be The optimized processing mode index attribute field is used to designate whether the sequential operrandom or either for performance created and maintained in a manner that optimizes ations. maximum entry length attribute field specifies the maximum length allowed for independent index maximum entry length allowed will be 120 bytes. If the that the maximum entry length entries will be 2000 bytes. is 2000 bytes, then Otherwise, the The key length field specifies the length of the key for the entries that are inserted into the argument length specifies the length of the the entries when fixed length entries are used. The key length must have a value less than or equal to the index. The argument length whether specified during is not used if The key length creation (for fixed-length entries) or during insertion (for variable length). the key insertion field specifies no insertion by key. The extension offset specifies the byte offset from the beginning of the operand 2 template to the template extension is beginning of the template extension. An offset value of zero specifies that the of 16 (to cause multiple be must a offset non-zero A invalid. is not provided. A negative offset value the offset value 16 byte alignment of the extension). Except for these restrictions, template. create the of correctness relative to the location of other portions is not verified for to override the The domain assigned field in the template extension allows the user of this instruction domain for this object that would otherwise be chosen by the machine. Valid values for Domain field Domain assigned to the object Hex 0000 The domain will be chosen by the machine. Hex 0001 The domain will be 'Common User'. Hex 8000 The domain will be 'Common System'. Any value specified for the this field are: domain assigned field other than those listed above will result in a template value invalid (hex 3801) exception being signalled. Limitations: The following are limits that apply to the functions performed by this instruction. The size of the object specific portion of the object is limited to a maximum of 4 gigabytes. and excludes dependent upon the amount of storage needed for the number and size of index entries This size the size of the associated space, The size of the associated space if is any. for this object is limited to a maximum of Chapter Independent Index Instructions 16MB-32 bytes. Authorization Required • • Insert - Context identified by operand 2 - User profile of object owner Retrieve - Contexts referenced for address resolution 11. 11-7 Create Independent Index (CRTINX) Lock Enforcement * Modify — — • Access group User operand identified by profile of object 2 owner Context identified by operand 2 Materialize Contexts referenced for address resolution Exceptions Operands Exception Access group 01 object ineligible for access group X 02 object exceeds available space 06 X Addressing 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 X x X x X x X X X x Argument/parameter 01 0A parameter reference violation Authorization 01 unauthorized for operation 0E X Context 01 duplicate object identification 10 X Damage encountered 04 system object damage 44 partial xxx xxx state 05, authority verification terminated 1A due to damaged object X system object damage Lock state 01 invalid lock state 1C X Machine-dependent exception 03 machine storage 04 object storage limit limit exceeded exceeded 09 auxiliary storage pool 20 Other 2 1 02 number X invalid X Machine support 02 machine check X 03 function check X 22 Object access 01 object not found X Chapter 11 . X Independent Index Instructions 11-8 Create Independent Index (CRTINX) Operands Exception 02 object destroyed 03 object suspended 24 X X Other 08 object compressed X Pointer specification does not exist Resource control X X X X X 03 pointer addressing invalid object limit 01 user profile storage limit X exceeded Space management 01 38 X X 02 pointer type invalid 36 2 07 authority verification terminated due to destroyed object 01 pointer 2E 1 X X space extension/truncation Template specification 01 X template value invalid Chapter 11. Independent Index Instructions 11-9 Destroy Independent Index (DESINX) Destroy Independent Index (DESINX) Op Code (Hex) Operand 0451 1 Index Operand 1: DESINX System pointer. ( var index Description: system pointer : A previously created index identified by operand 1 is destroyed, and addressability to the which addressability exists. The system pointer identified by operand 1 is not modified by the instruction, and a subsequent reference to the destroyed index through the pointer results in an object destroyed exception. object is removed from any context in Authorization Required • Object control - Operand • 1 1 Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — • Contexts referenced for address resolution Object control - Operand • 1 Modify — — — Access group which contains operand Context which addresses operand User profile 1 1 which owns index Exceptions Operand Exception Other 06 Addressing 01 space addressing violation A 02 boundary alignment A 03 range X 06 optimized addressability invalid 08 x Argument/parameter 01 parameter reference violation Chapter 11 . Independent Index Instructions 11-10 Destroy Independent Index (DESINX) Operand 1 Exception Authorization Other OA X 01 unauthorized for operation 10 Damage encountered 04 system object damage 05 authority verification terminated due to 44 1 partial X state damaged X object X system object damage X Machine-dependent exception 03 machine storage 20 22 24 limit 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification does not X exist 02 pointer type invalid X 03 pointer addressing invalid object X Resource control limit 01 user profile storage limit 36 X exceeded Machine support 01 pointer 2E X Lock state 01 invalid lock state 1C X X exceeded Space management 01 X space extension/truncation Chapter 11. Independent Index Instructions 11-11 Find Independent Index Entry (FNDINXEN) Find Independent Index Entry (FNDINXEN) Op Code (Hex) Operand 0494 1 Receiver Operand 1: Operand 2: System Operand 3: Space pointer. Operand 4: Space pointer. FNDINXEN Space Operand Index 2 Operand Option Operand 4 Search argument 3 list pointer. pointer. ( receiver var index optionjist search_argument space pointer ; system pointer ; space pointer ; space pointer ) Warning: The following information is subject to change from release and be prepared to adjust for changes with each new release to release. Use it with Description: This instruction searches the independent index identified by operand 2 according to the list (operand 3) and the search argument (operand 4)- then it returns the desired entry or entries in the receiver field (operand 1). The maximum size of the independent index entry is either 120 bytes or 2000 bytes depending on how the maximum entry length attribute field was specified when the index was created. search criteria specified in the option The option list is a variable-length area that identifies the type of search to be performed, the length of the search argument(s), the number of resultant arguments to be returned, the lengths of the entries returned, and the offsets to the entries within the receiver identified by the operand 1 space pointer The option list has the following format: • Rule option • Argument length • Argument • Occurrence count • Return count Char(2) UBin(2) offset Each entry that • Entry length • Offset is Bin(2) Bin(2) Bin(2) returned to the receiver operand contains the following: UBin(2) Bin(2) The ru le option identifies the type of search to be Search Type > performed and has the following meaning: Value (Hex) 0001 Meaning 0002 Find occurrences that are greater than Find equal occurrences of operand operand 4. 4. Chapter 11 . Independent Index Instructions 11-12 Find Independent Index Entry (FNDINXEN) < Value (Hex) 0003 > 0004 < 0005 Search Type Meaning Find occurrences that are less than operand 4. Find occurrences that are greater than or equal to operand 4, Find occurrences that are less than or equal to operand 4. index entry or entries. 0006 Find the Last 0007 Find the last index entry or entries. Between 0008 First Find all between the two argu- between requires that operand 4 be a 2-element array in which element 1 is the argument and element 2 is the ending argument. All arguments between (and including) the and ending arguments are returned, but the occurrence count specified is not exceeded. rule option to find starting starting If entries specified by operand 4 (inclusive). ments The first the index to contain both pointers and scalar data, then the search argument must be For the option to find between limits, both search arguments must be 16-byte aligned. was created 16-byte aligned. The rule option and the argument length determine the search criteria used for the index search. The argument length must be greater than or equal to one. The argument length for fixed-length entries must be less than or equal to the argument length specified when the index is created. the length of the search argument (operand 4) to be used for the index search. When the rule option equals first or last, the argument length field is ignored. For the The rule option to find between, the argument length field specifies the lengths of one array element. lengths of the array elements must be equal. The argument length field specifies The argument offset is the offset of the second search argument from the beginning of the entire argument field (operand 4). The argument offset field is ignored unless the rule option is find between. The occurrence count specifies the maximum number be returned. This value invalid (hex 3801) exception The return count spefcifies the the receiver (operand in is For the • to the • 1). If is value of 4095. If this value is exceeded, a template signaled. of index entries satisfying the search criteria that were returned this field is 0, no index arguments satisfied the search criteria. number each entry returned in the receiver (operand 1). The entry the length of the entry retrieved from the index. The offset has the following meaning: There are two length maximum field is limited to a of index entries that satisfy the search criteria to fields in the option first first entry, the offset byte of the first is list for the number of bytes from the beginning of the receiver (operand 1) entry. For any succeeding entry, the offset is the number of bytes from the beginning of the immediately preceding entry to the first byte of the entry returned. that are retrieved as a result of the Find Independent Index Entry instruction are always returned starting with the entry that is closest to or equal to the search argument and then proceeding away from the search argument. For example, a search that is for < (less than) or < (less than or The entries equal All to) returns the entries in order of decreasing value. the entries that satisfy the search criteria (up to the occurrence count) are returned starting at the location designated by the If the index was created operand to contain both pointers 1 space in the space pointer. and scalar data, then each returned entry is 16-byte aligned. Chapter 11. Independent Index Instructions 11-13 Find Independent Index Entry (FNDINXEN) If the index was created to contain scalar data only, then returned entries are contiguous. Every entry retrieved causes the count of the find operations to be incremented by is available through the Materialize Index Attributes instruction. value of this count 1, The current Authorization Required • Retrieve - Operand - Contexts 2 referenced for address resolution Lock Enforcement • Materialize - Operand - Contexts 2 referenced for address resolution Exceptions Operands Exception 2 1 06 Addressing 01 XXX XXX XXX XXX XXX space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0A parameter reference violation 4 X X X X X X Damage encountered 04 system object damage state X X X X 05 authority verification terminated due to damaged object 44 1A partial system object damage X X X X X Machine-dependent exception limit exceeded X Machine support 02 machine check X 03 function check 22 X Lock state 03 machine storage 20 X X 01 invalid lock state 1C Other Authorization 01 unauthorized for operation 10 3 X Object access 01 object not found X X X X 02 object destroyed X X X X 03 object suspended X X X X Chapter 11 . Independent Index Instructions 11-14 Find Independent Index Entry (FNDiNXEN) Operands Exception 07 authority verification terminated due to destroyed object 1 2 3 4 X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X X X X X 03 pointer addressing invalid object 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 38 Other X X space extension/truncation Template specification 01 template value invalid X 02 template size invalid X Chapter 11. Independent Index Instructions 11-15 Insert Independent Index Entry (INSINXEN) Insert Independent Index Entry (INSINXEN) Op Code (Hex) Operand 04A3 Operand 2 Argument 1 Index Operand 1: System Operand 2: Space pointer. Operand 3: Space pointer. system pointer ; space pointer ; space pointer argument i 3 list pointer. INSINXEN ( var index opt i on_l Operand Option st ) Warning: The following information is subject to change from release and be prepared to adjust for changes with each new release. to release. Use it with caution Description: This instruction inserts one or more new entries into the independent index identified by according to the criteria specified in the option list (operand 3). Each entry is inserted into the index at the appropriate location based on the binary value of the argument. No other collating sequence is supported. The maximum length allowed for the independent index entry is either 120 bytes or 2000 bytes depending on how the maximum entry length attribute field was specified when the index was created. operand 1 The argument (operand option The list for the Find 2) and the option list (operand 3) have the same format as the argument and Independent Index Entry instruction. r ule . option identifies Insert Type Value (Hex) 0001 Insert Inser* the type of insert to be performed and has the following meaning: w jth 0002 Meaning Authorization Insert unique argument Insert argument, replacing the replacement nonkey portion already Insert without Insert 0003 Insert replacement in if the key Update is the index argument only not already in if the key the index Insert is The insert rule option is valid only for indexes not containing keys. The insert with replacement rule option and the insert without replacement rule option are valid for indexes containing either fixed- or variable-length entries with keys. The duplicate key argument (hex 1801) exception is signaled for the following conditions: If the rule option is insert If the rule option is insert without replacement (operand 2) is already in and the argument to be inserted (operand 2) is already in and the key portion of the argument the index to be inserted the index The argument length and argument offset fields are ignored, however, the entry length and must be entered for every entry which is to be inserted into the index. Chapter 11 . offset fields Independent Index Instructions 11-16 Insert Independent Index Entry (INSINXEN) The occurrence count maximum specifies the value of 4095. If this of arguments to be inserted. This field is limited to a exceeded, a template value invalid (hex 3801) exception is number value is signaled. If the index was created 16-byte aligned. offset fields If the index was created must be specified The entry length If to contain both pointers the index is in and data then each entry the option list for each argument the space identified by operand in to contain both pointer and scalar data the offset , offset is the number previous entry to the beginning of the entry to be inserted. start of the space identified by operand 2. For the for be inserted must be and 2. the length of the entry to be inserted. was created be supplied to , to contain variable-length entries, then the entry length each entry to be inserted. The field in the option list must of bytes from the beginning of the entry, this first The return count specifies the number of entries inserted into the index. contain scalar data only, then any pointers inserted are invalidated. If is the index the offset from the was created to Authorization Required • Insert or update depending on insert type - Operand • 1 Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize • Contexts referenced for address resolution Modify - Operand 1 Exceptions Operands 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X X X 1 Exception 02 Access group 01 object 06 space addressing violation Argument/parameter 01 0A X exceeds available space Addressing 01 08 parameter reference violation Authorization X 01 unauthorized for operation 10 Other Damage encountered 04 system object damage X state Chapter 11. X Independent Index Instructions 11-17 Insert Independent Index Entry (INSINXEN) Exception U5 authority verification terminated due to 44 18 X X X X X Independent index argument in index X Lock state X Machine-dependent exception 03 machine storage 04 object storage 20 Other 3 object 01 invalid lock state 1C 2 1 damaged system object damage partial 01 duplicate key 1 Operands limit limit exceeded X exceeded X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found X X X 02 object destroyed X X X 03 object suspended X X X 07 authority verification terminated due to destroyed object X 08 object compressed 24 Pointer specification 01 pointer 2E does not exist X X X 02 pointer type invalid X X X 03 pointer addressing invalid object X Resource control limit 01 user profile storage limit 36 exceeded X Space management 01 38 X space extension/truncation X Template specification 01 template value invalid X 02 template size invalid X Chapter 11. Independent Index Instructions 11-18 Materialize Independent Index Attributes (MATINXAT) Materialize Independent Index Attributes Op Code Operand (Hex) Operand 1 Receiver 0462 Operand /: Space Operand 2: System (MATINXAT) 2 Index pointer. pointer. ILE access MATINXAT ( receiver var index space pointer ; : system pointer : ) Use Warning: The following information is subject to change from release to release. and be prepared to adjust for changes with each new release. Description: The instruction materializes the creation attributes the independent index identified by operand 2 into the space attributes materialized • • and current operational statistics of operand 1. The format of the as follows: Char(8) — Number Bin(4) of bytes provided for materialization bytes available for materialization Bin(4) Object identification Char(32) — Object type Char{1) — Object subtype Char(1) — Object name Char(30) Object creation options Char(4) — Bit 0 Bit 1 Existence attributes 0 1 = Temporary = Reserved — Space 0 1 — 1 — = = attribute Fixed-length Variable-length Bit 2 Context 0 = = Addressability not Addressability in in context context Access group 0 1 with caution identified by Materialization size specification — Number of • is it Bit 3 = Not a member of access group = Member of access group — Reserved (binary — Initialize Bits 4-12 0) space — Reserved Bit 13 Bits 14-31 (binary 0) Chapter 11 Independent Index Instructions 11-19 Materialize Independent Index Attributes • Reserved (binary • Size of space » Initial • Performance class Char(4) — Space Bit 0 0) (MATINXAT) Char(4) Bin(4) value of space Char(1) alignment The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space. If no space is specified for the object, this value must 0 be specified 1 = for the performance class. The space associated with the object is allocated to allow proper alignment of pointers 16-byte alignments within the space as well as to allow proper alignment of input/output at buffers at 512-byte alignments within the the space. — Reserved (binary - Main 0 1 0) Reserved (binary — Block transfer on implicit access state modification 1 Bit 5 — Process default main storage pool used for object. = Machine default main storage pool used for object. — 0 Bits 1-4 storage pool selection = — 0) Bit 6 Bit 7 The minimum storage transfer size for this object is a value of 1 storage unit. The machine default storage transfer size for this object is a value of 8 storage - Reserved (binary 0) units Bits 8-31 • Reserved (binary 9 Context System pointer 9 Access group System pointer 9 Index attributes Char(1) • Argument Bin(2) 9 Key length Bin(2) Index statistics Char(12) • 0) Char(7) length - Entries inserted - Entries - Find operations UBin(4) removed UBin(4) UBin(4) The first 4 bytes of the materialization identify the total number of bytes provided that may be used by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver tion requested, then the is greater than that required to contain the informaexcess bytes are unchanged. No exceptions other than naled in the materialization length (hex 3803) exception described previously are sigthe event that the receiver contains insufficient area for the materialization. Chapter 11. Independent Index Instructions 11-20 Materialize independent Index Attributes (MATINXAT) identified by the operand 1 space pointer must be 16-byte aligned. Values in the temremain the same as the values specified at the creation of the independent index except that the object identification, context, and size of the associated space contain current values. The template plate If the entry length index was is created. fixed, If then the argument length the entry length is is the value supplied variable, then the in argument length the template field is when the equal to the length of the longest entry that has ever been inserted into the index. The number of arguments in the index equals the number of entries inserted minus entries removed The value of the find operations field is initialized to 0 each time the index is materialized. The value may not be correct after an abnormal system termination. . Authorization Required • Operational — Operand • 2 Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Operand — 2 Contexts referenced for address resolution Exceptions Operands 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 0A parameter reference violation Authorization X 01 unauthorized for operation 10 XXX XXX Damage encountered 04 system object damage state 05 authority verification terminated due to 44 1A partial damaged X object system object damage Lock state X 01 invalid lock state 1C Other Machine-dependent exception 03 machine storage limit exceeded Chapter 11. Independent Index Instructions 11-21 Materialize Independent Index Attributes (MATINXAT) Operands Exception 22 Object access 24 1 2 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X 03 pointer addressing invalid object 2E Resource control X limit 01 user profile storage limit 36 exceeded X Space management 01 space extension/truncation 38 Other X Template specification 01 template value invalid X 03 materialization length exception X Chapter 11. Independent Index Instructions 11-22 Modify Independent Index (MODINX) Modify Independent Index (MODINX) Op Code Operand (Hex) Operand 1 Independent index 0452 2 Modification option Operand 1: System Operand 2: Character — pointer. scalar. (4) ILE access MODINX ( var index var modi fi cation_opti on : : system pointer-, aggregate ) Warning: The following information is subject to change from release and be prepared to adjust for changes with each new release. Description: Reserved (binary — Immediate 0 1 — • operand 2. New operand 2 Bit 0 0) Bit 1 = Do not change immediate update attribute = Change immediate update attribute Bits 2-7 0) Char(1) attribute value Reserved (binary — Immediate update — in Char(1) — 1 0) Bit 0 Bit 1 = No immediate update = Immediate update Reserved (binary Reserved (binary Bits 2-7 0) Char(2) 0) then the immediate update attribute If the modification selection immediate update is 0, If the modification selection immediate update bit is 1, new immediate update If The modification options specified update Reserved (binary 0 • in Modification selection — with caution it This instruction modifies the selected attributes of the independent index specified by operand 1 to have the values specified have the following format: • Use to release. the immediate update attribute is is not changed. changed to the attribute value. the immediate update attribute of the index was previously being modified to immediate update, then the index is set to no immediate update and , ensured before the attribute is it is modified. Authorization Required • Object management — Operand • 1 Retrieve Chapter 11. Independent Index Instructions 11-23 Modify Independent Index (MODINX) — Contexts referenced for address resolution Lock Enforcement • Modify — Operand • 1 Materialization — Contexts referenced for address resolution Exceptions Operands Exception01 06 1 2 Other Addressing 01 01 space addressing violation X X 02 boundary alignment X X 03 range X X X X 06 optimized addressability invalid 08 Argument/parameter parameter reference violation 0A Authorization unauthorized for operation 10 Damage encountered 04 system object damage 05. authority verification terminated 44 1A X partial X due to damaged X object system object damage X Lock state 01 invalid lock state 1C 22 24 X Machine-dependent exception 03 machine storage 20 X limit exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not X X 02 pointer type invalid X X 03 pointer address invalid object X exist Chapter 11. Independent Index Instructions 11-24 Modify Independent Index (MODINX) Operands Exception 2E 1 Resource control X exceeded Scalar specification X 01 scalar type invalid X X 02 scalar attributes invalid 36 Other limit 01 user profile storage limit 32 2 Space management 01 X space extension/truncation Chapter 11. Independent Index Instructions 11-25 Remove Independent Remove Independent Index Op Code Operand (Hex) 0484 Operand 1: Operand 2: System Operand 3\ Space pointer. Operand 4: Space pointer. Space pointer or RMVINXEN ( receiver (RMVINXEN) Entry 1 Receiver Index Entry (RMVINXEN) Operand Index 2 Operand Option 3 list Operand 4 Argument null. pointer. space pointer-, OR null operand-, var index optionjist argument system pointer; space pointer; space pointer ) Warning: The following information is subject to change from release and be prepared to adjust for changes with each new release. to release. Use it with caution The index entries identified by operands 3 and 4 are removed from the independent index identified by operand 2 and optionally returned in the receiver specified by operand 1. The maximum length of an independent index entry is either 120 bytes or 2000 bytes depending on how the maximum entry length attribute field was specified when the index was created. Description: The option (operand 3) and the argument (operand 4) have the same format and meaning as the and argument for the Find Independent Index Entry instruction. The return count designates the number of index entries that were removed from the index. option list list The arguments removed are returned in the receiver field if a space pointer is specified for operand 1. If operand 1 is null, the entries removed from the index are not returned. If neither space pointer nor null is specified for operand 1, the entries are returned in the same way that entries are returned for the Find Independent Index Entry instruction. Every entry removed causes the occurrence count to be incremented by 1. The current value of this count is available through the Materialize Index Attributes instruction. The occurrence count field must be less then 4096. Authorization Required • Delete — Operand • 2 Retrieve - Contexts referenced for address resolution Chapter 11. Independent Index Instructions 11-26 Remove Independent Index Entry (RMVINXEN) Lock Enforcement • Materialize — • Contexts referenced for address resolution Modify — Operand 2 Exceptions Operands Exception 02 1 X X X X 02 boundary alignment X X X X 03 range X X X X X X X X X X X X X X space addressing violation Argument/parameter 01 parameter reference violation Authorization X 01 unauthorized for operation 10 Damage encountered 04 system object damage 44 partial X state 05 authority verification terminated due to 1 damaged 24 X X X X Lock state X X Machine-dependent exception 04 object storage 22 X X X system object damage 03 machine storage 20 X object 01 invalid lock state 1C Other X exceeds available space 06 optimized addressability invalid 0A 4 Addressing 01 08 3 Access group 01 object 06 2 limit limit X exceeded X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X X X 02 object destroyed X X X X 03 object suspended X X X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not X exist Chapter 11. X X X Independent Index Instructions 11-27 Remove Independent Index Entry (RMVINXEN) Operands Exception 02 pointer type invalid 03 pointer addressing invalid object 2E Resource control 36 3 4 X X Other X exceeded X Space management 01 38 2 X limit 01 user profile storage limit J 1 X space extension/truncation X Template specification 01 template value invalid X 02 template size invalid X Chapter 11 . Independent Index Instructions 11-28 Queue Management Chapter 12. Queue Management Instructions Instructions This chapter describes the instructions used for queue management. These instructions are betic order. For an alphabetic summary of all in alpha- the instructions, see Appendix A, “Instruction Summary.” Dequeue (DEQ) Enqueue (ENQ) Materialize Materialize © Queue Attributes (MATQAT) Queue Messages (MATQMSG) Copyright IBM Corp. 1991, 1993 12-3 12-9 12-12 12-16 12-1 Queue Management Chapter 12. Queue Management Instructions Instructions 12-2 Dequeue (DEQ) Dequeue (DEQ) Op Code DEQ Extender (Hex) Operand Message Operand Operand 2 Message text 1 Queue Operand 4-5 queue tem- prefix 1033 3 or plate DEQB Branch options 1C33 Message Message Queue text or Branch targets queue tem- prefix plate DEQI Indicator Message 1833 options prefix Message Queue text or Indicator targets queue template Operand 1: Character variable scalar (fixed-length). Operand 2: Space Operand 3: System pointer or space pointer data Operand 4-5: pointer. • Branch Form - Branch number. • Indicator — point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. — ILE access DEQ object. ( aggregate-, var message_prefix message_text space pointer-, system pointer-, var queue signed binary /* return_code */ : : : ) : If a message is not available, this instruction will return immediately with the return code set as follows: Return_Code Meaning 1 Message Dequeued. 6 Message Not Dequeued. OR DEQWAIT ( var msg_prefix msg_text var queue : : : aggregate-, space pointer-, system pointer ) If a message is not available, this instruction will wait until message is available. Chapter a 12. Queue Management Instructions 12-3 Dequeue (DEQ) The instruction retrieves a queue message based on the queue type (FIFO, LIFO, or keyed) specified during the queue's creation. If the queue was created with the keyed option, messages can be retrieved by any of the following relationships between an enqueued message key and a selection key specified in operand 1 of the Dequeue instruction: >, <, <, and >. If the queue was created with either the LIFO or FIFO attribute, then only the next message can be retrieved from the queue. Description: If a message is not found that satisfies the dequeue selection criterion and the branch or options are not specified, the process waits until a message arrives to satisfy the dequeue or until the dequeue wait time-out expires. If branch or indicator options are specified, the process is not placed in the dequeue wait state and either the control flow is altered according to the branch options, or indicator values are set based on the presence or absence of a message to be dequeued. If operand operand 3 a system pointer, the message is dequeued from the queue specified by operand 3. If a space pointer, the message is dequeued from the queue which is specified in the template pointed to by the space pointer. The format of this template is given later in this section. The 3 criteria for text is is is message returned selection are given in the message prefix specified by operand 1. The message the space specified by operand 2, and the message prefix is returned in the scalar in specified by operand message • • prefix Timestamp Size of (The • Improper alignment results in an exception being signaled. The format of the enqueue of message Char(8)** Dequeue wait time-out value (ignored • of 1. as follows: is if Char(8)* branch options specified) message dequeued maximum Bin(4)** allowable size of a queue message is 65 000 bytes.) Access state modification option indicator and message — Access when Bit 0* Access state modification option when Bit 1* state modification option entering 0 1 — = = 0 1 = = Dequeue wait Access state Access state leaving 0 1 not modified modified Access state Access state is not modified is modified level option Bit 2* = Leave current MPL set at Dequeue wait = Remain in current MPL set at Dequeue wait Time-out option 0 1 — is is Dequeue wait — Multiprogramming — Char(1)* selection criteria = = Bit 3* Wait for specified time, then signal time-out exception Wait indefinitely Actual key to input key relationship (for Bits 4-7* keyed queue) 0010: Greater than 0100: Less than 0110: Not equal 1000: Equal 1010: Greater than or equal 1100: Less than or equal Chapter 12. Queue Management Instructions 12-4 Dequeue (DEQ) • » Search key (ignored for FIFO/LIFO queues but must be present for FIFO/LIFO queues with nonzero key length values) Char(key Message key Char(key length) length)** Note: Fields shown here with one asterisk indicate input to the instruction, and fields shown here with two asterisks are returned by the machine. wait time-out value overrides any dequeue wait time-out value specified as the time-out value to be current process attribute. A zero dequeue wait time-out value causes the wait the Dequeue instruction (from are values 0 time-out taken from the current process attribute. If all wait is signaled. The exception 3A01) (hex and the current process attribute), an immediate wait time-out The maximum microseconds. 1024 as bits in this field are numbered from 0 to 63, and bit 41 is defined that indivalue (2*> Any microseconds. 1) dequeue wait time-out interval allowed is a value equal to used. to be time-out wait cates more time than the maximum wait time-out causes the maximum A nonzero dequeue message The size of the message dequeued is returned in the message prefix. The size of the queue was the when specified message dequeued can be less than or equal to the maximum size of length of the and the field key created. When dequeuing from a keyed queue, the length of the search by the implicitly determined message key field (in the message key prefix specified in operand 1) are the pointers, contains attributes of the queue being accessed. If the message text on the queue aligned. 16-byte must be operand text message The access state of the process access group and the following conditions exist: The process' - is modified when a Dequeue instruction results in a wait state instruction wait initiation access state control attribute specifies allow access modification state modification option specifies modify access state . The dequeue access • The multiprogramming level option specifies leave MPL set during wait. MPL set for a maximum of two seconds when a Dequeue level option specifies remain in current MPL set at multiprogramming the instruction results in a wait if entering Dequeue wait option specifies do not when modification Dequeue wait and the access state automatically be removed from the current will process the access state. After two seconds, The process will remain in the current modify The automatic removal does not change or by the Dequeue wait time-out value. MPL set. affect the total wait time specified for the process be can be a system pointer or a space pointer. If it is a system pointer, this pointer will pointer this pointer, space is a If it dequeued. be is to addressing the queue from which the message pointer to the queue as well as the will be addressing a template which will contain the system and must be aligned on a 16-byte length Dequeue template extension. The template is 32 bytes in Operand 3 boundary with the format as follows: • Queue System pointer • Dequeue template extension Char(16) — Char(1) Extension Options - Modify process event 0 1 - - = Do not = Modify mask modify process event process event mask Reserved (binary BitO option * mask Bits 1-7 0) Char(15) Extension Area Chapter 12. Queue Management Instructions 12-5 Dequeue (DEQ) - - - New process event mask Previous process event Reserved (binary The mask Bin(2) 0) The Previous process event mask D66H S6I lO 1 Note: Bin(2) * ** Char(11) only returned is when the modify process event Fields shown here with one asterisk indicate input two asterisks are returned by the machine, to the instruction, and mask fields option has shown here with mo dify Process event masjc option controls the state of the event mask in the process executing If the modify process event mask field specified to modify the process event mask the process event mask will be changed as specified by the new process event mask field. When the' process event mask is changed, the current process event mask will be returned in the H previous process event mask field. this instruction. If the system security level machine attribute state then the modify process event exception is is hex 40 or greater and the process is running in user is not allowed and a template value invalid (hex 3801) v mask option ; signalled. he piocess event mask is in the masked state, the machine does not schedule signaled event monim he process The event monitors continue to be signaled by the machine or other processes. When i the process is modified to the unmasked state, event handlers are scheduled to handle those events that occurred while the process was masked and those events occurring while in the unmasked 3 e lhe number of signals retained while the process is masked is specified by the attributes of the event monitor associated with the process. LT ; , The process masked by the machine when event handlers are invoked If the process the event handler, other events can be handled if another enabled event monitor within that process is signaled. If the process is masked when it exits from the event handler the machine explicitly unmasks the process. is unmasked Valid 0 256 automatically is in masking values are: Masked Unmasked Other values are reserved and must not be specified. value invalid (hex 3801) exception is signaled. If any other values are specified, a template Whether masking or unmasking the current process, the new mask takes satisfied dequeue. effect upon completion of a Resultant Conditions message dequeued * Equal * N °f equal - - message not dequeued Authorization Required •• Retrieve — Operand — Contexts 3 referenced for address resolution Chapter 12. Queue Management Instructions 12-6 Dequeue (DEQ) Lock Enforcement - Materialize - Contexts referenced for address resolution Exceptions Operands 06 2 3 X X X 02 boundary alignment X X X 03 range X X X 06 optimized addressability invalid X X X X X X Addressing 01 08 space addressing violation Argument/parameter 01 0A parameter reference violation Authorization 01 unauthorized for operation 10 Other 1 Exception X X X X Damage encountered X 04 system object damage state X X 05 authority verification terminated due to damaged object 44 1 partial X system object damage X X limit X exceeded Machine support X 02 machine check X 03 function check 22 Object access X 01 object not found X 02 object destroyed X X X 03 object suspended X X X X 07 authority verification terminated due to destroyed object X 08 object compressed 24 Pointer specification X X X 02 pointer type invalid X X X 03 pointer address invalid object X 01 pointer 2E X Machine-dependent exception 03 machine storage 20 X Lock state 01 invalid lock state 1C X does not Resource control exist limit 01 user profile storage limit exceeded Chapter 12. Queue Management Instructions 12"? Dequeue (DEQ) 12 Operands Exception 32 Scalar specification 03 scalar value invalid 36 X Space management 01 3A Other 3 space extension/truncation X Wait time-out 01 dequeue X Chapter 12. Queue Management Instructions 12-8 Enqueue (ENQ) Enqueue (ENQ) Op Code Operand (Hex) Operand 1: System Operand 2: Character scalar. Operand 3: Space Operand 3 Message text Operand 2 Message prefix 1 Queue 036B pointer. pointer. ILE access 1 ENQ ( var queue var message_prefix message text system pointer-, aggregate-, space pointer ) Description: A message is enqueued according to the queue type attribute specified during the queue's creation. enqueued messages are sequenced in ascending binary collating order according to the key value. If a message to be enqueued has a key value equal to an existing enqueued key value, the message being added is enqueued following the existing message. If keyed sequence is specified, was defined with either last in, first out (LIFO) or first in, first out (FIFO) sequencing, then enqueued messages are ordered chronologically with the latest enqueued message being either first on the queue or last on the queue, respectively. A key can be provided and associated with messages enqueued in a LIFO or FIFO queue; however, the key does not establish a message's position in the queue. The key can contain pointers, but the pointers are not considered to be pointers when they are the queue If placed on the queue by an Enqueue instruction. Operand message 1 prefix, The format queue to which a message is to be enqueued. Operand and operand 3 specifies the message text. specifies the of the message message to be prefix is 2 specifies the as follows: Bin(4) enqueued • Size of * Enqueue key value (Ignored for FIFO/LIFO queues with key lengths equal to 0. Char(key length) The size of the message to be enqueued is supplied to inform the machine of the number of bytes in the the space that are to be considered message text. The size of the message is then considered specified on size lesser of the size of the message to be enqueued attribute and the maximum message the queue creation. The message text can contain pointers. When pointers are in message text, operand 3 space pointer must be 16-byte aligned. Improper alignment will result in an exception being signaled. If the enqueued sages » If attribute the queue message causes of the queue, one is the number of messages to exceed the maximum number of mes- of the following occurs: not extendable, the queue message limit exceeded (hex 2602) exception and the message is not enqueued. queue message limit exceeded (hex 0012,03,01) event are signaled. The Chapter 12. Queue Management Instructions 12-9 Enqueue (ENQ) If the queue message is extendable, the queue is implicitly enqueued. No exception is signaled, but the is extended by the extension value attribute. The queue extended (hex 0012 04 01) event is ’ ’ signaled. The maximum allowable queue head, is size, including all messages currently 16 megabytes. enqueued and the machine over- Authorization Required • Insert - Operand • 1 Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize - Contexts referenced for address resolution Exceptions Operands Exception 06 01 08 space addressing violation X X X X X 03 range X X X 06 optimized addressability invalid X X X X X X parameter reference violation Authorization X 44 damage state partial to damaged X X X X X X X X object X system object damage Lock state 01 invalid lock state X X X X Machine-dependent exception 03 machine storage 04 object storage 20 X Damage encountered 05 authority verification terminated due 1C limit limit exceeded exceeded X Machine support 02 machine check x 03 function check 22 Other Argument/parameter 04 system object 1A 3 X 01 unauthorized for operation 10 2 02 boundary alignment 01 0A 1 Addressing X Object access Chapter 12 . Queue Management Instructions 12-10 Enqueue (ENQ) Operands XXX XXX XXX 1 Exception 01 object not found 02 object destroyed 03 object suspended 24 08 object compressed X 02 pointer type invalid XXX XXX 03 pointer address invalid object X Pointer specification does not exist Process management Resource control limit X exceeded limit 01 user profile storage limit 36 Other X 02 queue message 2E 3 07 authority verification terminated due to destroyed object 01 pointer 26 2 X exceeded Space management X 01 space extension/truncation Chapter 12. Queue Management Instructions 12-11 Materialize Queue Materialize Op Code (Hex) Attributes Operand 0336 1 Operand 2: Space : MATQAT | System I Operand 1 2 Queue pointer. — ( receiver var queue I (MATQAT) pointer. ILE access 1 Attributes (MATQAT) Receiver Operand Queue : space pointer system pointer ; : ) I Descnption: The attributes of the queue specified by operand 2 are materialized into the object speciby operand 1. The format of the materialized queue attributes must be aligned on a 16-byte muly tiple. The format is as follows: fied - Materialization size specification - Number of bytes — Number of bytes 9 8 Char(8) provided for materialization Bin(4) available for materialization Bin(4) Object identification — Object type — Object subtype - Object Char(32) Char(1) Char(1) name Char(30) Object creation options — 0 1 — 1 1 — = = = = attribute Bit Variable-length context Bit 2 Addressability not in context Addressability in context Access group 0 1 1 Fixed-length Initial 0 BitO = Temporary = Permanent Space 0 — Char(4) Existence attributes Bit 3 = Not a member of access group = Member of access group — Reserved (binary — Initialize — Reserved (binary 0) Bits 4-12 space • Reserved (binary 9 Size of space Bit 13 0) Bits 14-31 0) Char(4) Bin(4) Chapter 12. Queue Management Instructions 12-12 Materialize Initial Queue Attributes Char(1) value of space Performance class Char(4) — Bit 0 Space alignment 0 = The (MATQAT) space associated with the object 16-byte alignments within the space. is If allocated to allow proper alignment of pointers at no space is specified for the object, this value must be specified for the performance class. = 1 jhe space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space as well as to allow proper alignment of input/output buffers at 512-byte alignments within the the space. - Reserved (binary — Main storage pool selection 0 1 Bits 1-4 0) = Process default main storage pool is used for object. = Machine default main storage pool is used for object. — Reserved (binary — Block transfer on implicit access state modification 0 1 — Bit 5 = = Transfer the Bit 6 0) minimum storage Transfer the machine Reserved (binary Reserved (binary Bit 7 transfer size for this object. default storage transfer size. This value This value is 8 is 1 storage Bits 8-31 0) Char(7) 0) Context System pointer Access group System pointer Queue Char(1) attributes — Message 0 1 = = unit. storage units. Bit 0 content Contains scalar data only Contains pointers and scalar data — Queue type 00 = Keyed 01 = Last in, 10 = First in, Bits 1-2 first out first out — Queue overflow action 0 = Signal exception = Extend queue Bit 3 - Bits 4-7 - 1 Reserved (binary 0) messages Bin(4) Current number of messages enqueued Bin(4) Extension value Bin(4) Key Bin(2) Current maximum number length Maximum The first of size of message to be enqueued 4 bytes of the materialization identify the total Bin(4) number of bytes provided for use by the instruc- not modified by the instruction. supplied as input to the instruction and is of less than 8 causes the materialization length (hex 3803) exception. tion. This value is Chapter 12. Queue Management A Instructions value 12-13 Materialize Queue Attributes (MATQAT) The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exceptions (other than the materialization length (hex 3803) exception described previously) are signaled when the receiver contains insufficient area for the materialization. tion requested, then the See the Create Queue (CRTQ) instruction for a description of these fields. Authorization Required • Operational - Operand • 2 Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize - Operand - Contexts 2 referenced for address resolution Exceptions Operands Exception 06 01 08 2 space addressing violation X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X parameter reference violation Authorization 01 unauthorized for operation 10 04 system object 44 damage state partial X damaged X X X object X system object damage X X X X X Lock state 01 invalid lock state 20 X Damage encountered 05 authority verification terminated due to 1 Machine support 02 machine check X 03 function check 22 Other Argument/parameter 01 OA 1 Addressing X Object access 01 object not found X Chapter 12 . Queue Management X Instructions 12-14 Materialize Queue Attributes (MATQAT) Operands Exception 02 object destroyed 03 object suspended 24 1 2 X X X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X 03 pointer address invalid object 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 38 Other X space extension/truncation Template specification X 03 materialization length exception Chapter 12. Queue Management Instructions 12-15 Materialize Queue Messages (MATQMSG) Queue Messages (MATQMSG) Materialize Op Code (Hex) 033B Operand Operand 1 Receiver Operand 3 Message selection 2 Queue template Operand 1: Operand 2: System Operand 3: Character(16) scalar (fixed length). Space pointer. pointer. — ILE access 1 MATQMSG ( recei ver space pointer ; system pointer ; aggregate : var queue var selection template : : ) Description: This instruction materializes selected messages on a queue. One or more messages on the queue specified by operand 2 is selected according to information provided in operand 3 and materialized into operand 1. The number of messages materialized and the amount of key and message each message is governed by the message selection template. text data materialized for Note that the basis. queue list of messages on a queue is a dynamic attribute and may be changing on a continual The materialization of messages provided by this instruction is just a picture of the status of the at the point of interrogation by this instruction. As such, the actual status of the queue may from that described in the materialization when subsequent instructions use the information in the template as a basis for operations against the queue. differ Operand 1 Operand 2 is a system pointer Operand 3 is a character specifies a space that The operand 1 (16) is to receive the materialized attribute values. identifying the queue from which the messages are scalar specifying which messages are to be materialized. to be materialized. space pointer must address a 16-byte boundary. The materialization template has the following format: • • Materialization size specification of bytes provided for materialization Bin(4) — Number of bytes available for materialization Bin(4) Materialization data — • Char(8) — Number Char(4) Count of messages materialized Bin{4) Queue data — Char(12) Count of messages on the queue — Maximum message — Key size ° Reserved • Message data (repeated Bin(4) size Bin(4) Bin(4) Char(8) for each message) Char(*) Chapter 12. Queue Management Instructions 12-16 Materialize Message • Char(16) attributes — Message enqueue — Message length — Queue Messages (MATQMSG) Char(8) time Bin(4) Reserved Char(4) • Message key Char(*) • Message Char(*) The text 4 hvtes of the materialization identify the total first This value tion. is number supplied as input to the instruction and is of bvtes provided for use by the instruc- not modified by the instruction. A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. The sftrnnrl 4 bytes of the materialization identify the total instruction materializes as The ized. many number of bvtes available to bytes as can be contained in be material- the area specified as the greater than that required to contain the information requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length (hex receiver. the byte area identified by the receiver If is 3803) exception described previously. The maximum messaqe size and kev size are values specified when the queue was created. queue is not a keyed queue, the value materialized for the key size is zero. The length of the message key and message message selection data. remaining space will If in is Message - is Char(2) Bits 0-3 = 0010 = = 0010 0100 0110 1000 1010 1100 — All = messages First Last Keyed other values are reserved — Key All relationship = = = = = = (if Bits 4-7 needed) Greater than Less than Not equal Equal Greater than or equal Less than or equal other values are reserved Bits 8-15 Reserved Char(8) Lengths — Number — Number • Reserved • Key (if and must be on a as follows: selection 0001 All • at least 16 bytes Type 0100 1000 3, be padded with binary zeros. The message selection template identified by operand 3 must be 16-byte boundary. The format of the message selection template • the determined by values supplied in operand operand 3 exceeds the actual data length, the text fields the length supplied If Bin(4) of key bytes to materialize of message Bin(4) text bytes to materialize Char(6) Charf) needed) Chapter 12. Queue Management Instructions 12-17 Materialize The message selection type must not specify keyed if the queue was Queue Messages (MATQMSG) not created as a keyed queue. Both of the fields specified under lengths must be zero or an integer multiple of 16. The maximum value allowed for the key length is 256. The maximum value allowed for the message text is 65536. Authorization Required • Retrieve - Operand - Contexts 2 referenced for address resolution Lock Enforcement • Materialization - Operand - Contexts 2 referenced for address resolution Exceptions Operands Exception 06 1 Addressing 01 03 range 06 optimized addressability invalid Argument/parameter 01 0A parameter reference violation damage X state 05 authority verification terminated due to 44 partial damaged object X system object damage X Lock state 01 invalid lock state 20 X Machine support 02 machine check X 03 function check 22 Other Damage encountered 04 system object 1A 4 Authorization 01 unauthorized for operation 10 3 XXX XXX XXX XXX XXX space addressing violation 02 boundary alignment 08 2 X Object access XXX XXX XXX 01 object not found 02 object destroyed 03 object suspended 07 authority verification terminated due to destroyed object X 08 object compressed X Chapter 12. Queue Management Instructions 12-18 Materialize Queue Messages (MATQMSG) Operands Exception 24 1 2 3 X X X X X 01 pointer does not exist X 02 pointer type invalid Process state X 02 process control space not associated with a process 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification 01 scalar type invalid X X X 02 scalar attributes invalid X X X X 03 scalar value invalid 36 Space management 01 38 Other X 03 pointer address invalid object 28 4 Pointer specification X space extension/truncation Template specification X 03 materialization length exception Chapter 12. Queue Management Instructions 12-19 Object Lock Chapter 13. Object Lock This chapter describes the lock For an alphabetic summary of Management management all instructions. © Copyright IBM Corp. 1991, 1993 Instructions Instructions The instructions are in alphabetic order. the instructions, see Appendix A, Lock Object (LOCK) Lock Space Location ( LOCKS L) Materialize Data Space Record Locks (MATDRECL) Materialize Process Locks (MATPRLK) Materialize Process Record Locks (MATPRECL) Materialize Selected Locks (MATSELLK) Transfer Object Lock (XFRLOCK) Unlock Object (UNLOCK) Unlock Space Location (UNLOCKSL) Management “Instruction Summary.” 13-3 13-8 13-13 13-17 13-20 13-24 13-27 13-30 13-33 13-1 Object Lock Chapter 13. Management Instructions Object Lock Management Instructions 13-2 Lock Object (LOCK) Lock Object (LOCK) Op Code Operand (Hex) 1 Lock request tem- 03 F5 plate Operand — Space 1: pointer. ILE access LOCK ( lock_request_template : space pointer ) The instruction requests that locks for system objects identified by system pointers in the space object (operand 1) be allocated to the issuing process. The lock state desired for each object is specified by a value associated with each system pointer in the lock template (operand 1). Description: The lock request template must be aligned on a 16-byte boundary. The format is as follows: • Number ° Offset to lock state selection values Bin(2) 3 Wait time-out value for instruction Char(8) • Lock request options Char(1) — Bits 0-1 of lock requests in template Bin(4) Lock request type 00 = Immediate request- If all locks cannot be immediately granted, signal lock request not grantable (hex 1A02) exception. 01 10 = = Synchronous request- Wait until all locks can be granted. Asynchronous request- Allow processing to continue and signal event when the object is available. — Access state modifications - When the process is Bits 2-3 entering Bit 2 lock wait for synchronous request: 0= = 1 - Access state should not be modified. Access state should be modified. When 0= 1= Reserved (binary — Time-out option Wait Wait - Template 0= is leaving lock wait: Bit 3 Access state should not be modified. Access state should be modified. — 0= 1 = • the process Bits 4-5* 0) Bit 6 for specified time, then signal time-out exception. indefinitely. extension specified Template is not specified. 1= Template is specified. Reserved (binary 0) Bit 7 Char(1) Chapter 13. Object Lock Management Instructions 13-3 Lock Object (LOCK) The Lock Object template extension is only present if template extension specified Otherwise, the Object(s) to be locked should immediately follow. • indicated above. Lock Object template extension Char(16) - Char(1) Extension options Modify process event - 0 1 - = Do not = Modify mask option modify process event process event mask Reserved (binary - • is Bit mask Bits 1-7 0) Extension area Char(15) - New - Previous process event - Reserved (binary process event mask UBin(2) mask UBin(2) Char(11) 0) Object(s) to be locked System pointer This should be repeated as specified by The lock state selection 0 is number of lock requests in template above. located by adding the offset to lock state selection values above to operand 1. • Lock state selection Char(1) (repeated for each pointer - in the template) Requested lock state = (1 Bits 0-4 lock requested, 0 = lock not requested) Only one state may be requested. - - LSRD LSRO LSUP LEAR LENR lock Bit 0 lock Bit 1 lock Bit 2 lock Bit 3 lock Bit 4 - Reserved (binary - Entry active indicator 0 1 Note: = = Entry not active Entry active Bits 5-6* 0) - - Bit 7 This entry is not used. Obtain this lock. Entries indicated with an asterisk are ignored by the instruction. Lock Allocation Procedure: A single Lock instruction can request the allocation of one or more lock states on one or more objects. Locks are allocated sequentially until all locks requested are allocated. The offset to lock state selection values specifies offset is an offset from the beginning of the lock request. This used to locate the lock state selection values. The wait time-out field establishes the maximum amount of time that a process competes for the requested set of locks when either lock request type is either synchronous or asynchronous. The bits in this field are numbered from 0 to 63, and bit 41 is defined as 1024 microseconds. The maximum wait time-out interval allowed is a value equal to (2 48 - 1) microseconds. Any value that indicates more time than the maximum wait time-out causes the maximum wait time-out to be used. If the wait time-out field is specified with a value of binary 0, then the value associated with the default wait time-out field in the process definition template establishes the time interval. Chapter 13. Object Lock Management Instructions 13-4 Lock Object (LOCK) When a requested lock state cannot be immediately granted, any locks already allocated by this Lock and the lock request type specified instruction are released, the machine action. The lock request types are described • Immediate Request- If in in the lock request template establishes the following paragraphs. the requested locks cannot be granted immediately, this option causes the lock request not grantable (hex 1A02) exception to be signaled. request • is No locks are granted and the lock canceled. Synchronous Request- This option causes the process requesting the locks to be placed in the wait requested locks can be granted. If the locks cannot be granted in the time interval established by the wait time-out field specified in the lock request template, the lock wait time-out (hex 3A02) exception is signaled to the requesting process at the end of the interval. No locks are state until all granted, and the lock request • is canceled. Asynchronous Request- This option allows the requesting process to proceed with execution while the machine asynchronously attempts to satisfy the lock request. When the synchronous request option specified and the requested locks cannot be immediately allo- is cated, the access state modification field state of the process access group is the lock request template specifies whether the access in to be modified on entering and/or returning from the lock wait. The field has no effect if the process instruction wait access state control attribute specifies that no access state modification is allowed. If the process attribute value specifies that access state modification is allowed and the wait on event access state modification option specifies modify access state, the machine modifies the access state for the specified process access group. If the lock request type then the lock request If the lock request is requesting process. field specified in is synchronous and the invocation containing the lock instruction satisfied, If is terminated, canceled. is then the object locked (hex 000A,01,01) event the request is not satisfied in is signaled to the the time interval established by the wait time-out the lock request template, the asyncronous lock wait timeout (hex 000A,04,01) event signaled to the requesting process. No locks are granted, and the lock request is an object is destroyed while a process has a pending request to lock the object, the object destroyed (hex 000A,02,01) event is signaled to the waiting process. If the lock request type is is canceled. asynchronous and the invocation containing the Lock instruction is If terminated, then the lock request remains active. When two or more processes are competing for a conflicting lock allocation on a system object, the machine attempts to first satisfy the lock allocation request of the process with the highest priority. Within that priority, the machine attempts to satisfy the request that has been waiting longest. If any exception is identified during the instruction's execution, instruction are released, and the lock request is any locks already granted by the canceled. For each system object lock, counts are kept by lock state and by process. granted, the appropriate lock count(s) of each lock state specified If a previously unsatisfied lock request is satisfied is When a lock request incremented by is 1. by the transfer of a lock from another process, the lock request and transfer lock are treated as independent events relative to lock accounting. The appropriate lock counts are incremented for both the lock request and the transfer lock function. The modify process event mask option controls the this instruction. If mask masked state of the event mask in the process executing machine does not schedule signaled the process. The event monitors continue to be signaled by the machine or other the event is in the state, the event monitors in processes. When the process is modified to the unmasked state, event handlers are scheduled to handle those events that occurred while the process was masked and those events occurring while Chapter 13. Object Lock Management Instructions in 13-5 Lock Object (LOCK) the unmasked state. The number of events retained while the process is masked is specified by the attributes of the event monitor associated with the process. A lock request with an asynchronous lock request type cannot have the modify process event option set to mask 1 the system security level machine attribute is hex 40 or greater and the process is running in user then the modify process event mask option is not allowed and a template value invalid (hex 3801) exception is signalled. If | state, | | When the modify process event mask is set to 1, the previous process event mask will be returned and new process event mask will take effect only when the lock(s) have been successfully granted. If the the lock request is not successful, the previous process event new process event mask The process is unmasked that process explicitly Valid 0 256 is in is take mask value is not returned, nor does the effect. masked by the machine when event handlers are invoked. If the process the event handler, other events can be handled if another enabled event monitor within signaled. If the process is masked when it exits from the event handler, the machine automatically unmasks the process. masking values are: Masked Unmasked Other values are reserved and must not be specified. value invalid (hex 3801) exception is If any other values are specified, a template signaled. Whether masking or unmasking the current process, the new mask takes effect upon completion of a satisfied lock object. Authorization Required • Some — • authority or ownership Objects to be locked Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 06 01 08 1 Other Addressing space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter Chapter 13. Object Lock Management Instructions 13-6 Lock Object (LOCK) 01 Operands Exception01 1 0A Authorization unauthorized for operation 10 X Damage encountered 04 system object damage state X 05 authority verification terminated due to damaged object 44 1A partial system object damage X X X Machine-dependent exception 03 machine storage 06 machine lock 22 24 limit limit X exceeded X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not X exist X 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 38 space extension/truncation X Template specification X 01 template value invalid 3A X Lock state 02 lock request not grantable 20 X X 01 invalid lock state 1C Other X parameter reference violation Wait time-out X 02 lock Chapter 13. Object Lock Management Instructions 13-7 Lock Space Location (LOCKSL) Lock Space Location (LOCKSL) Op Code Operand 1 Space location or (Hex) 03F6 Operand 2 Lock request Lock Request Template Operand 1: Space pointer data Operand 2: Char(1) scalar or LOCKSL ( var space_l ocation var lock_request : : object. null. space pointer ; aggregate OR null operand ) When operand 2 is not null, the space location (operand 1) is granted to the issuing process according to the lock request specified by operand 2. When operand 2 is null, the instruction requests that the space locations identified in the lock request template (operand 1) be granted to the Description: issuing process. Locking a space location does not prevent any byte operation from referencing that location, nor does prevent the space from being extended, truncated, or destroyed. Space location locks follow the it normal locking rules with respect to A space the format of operand 2 is when not symbolic = - — null: if lock not requested) may be requested. Bit 0 lock Bit 1 lock Bit 2 lock Bit 3 lock Bit 4 Bits 5-7 0) the requested lock cannot be immediately granted, the process will enter a synchroup to the interval specified by the process default time-out value. a space location lock wait exception is signaled, and the requested for the lock for a period of the wait exceeds this time is = lock Reserved (binary nous wait Bits 0-4 lock requested, 0 LSRD LSRO LSUP LEAR LENR For this form, nature. Char(1) Only one state - in 1. Lock state selection (1 lock strictly Lock request — If and waits but are pointer machine object cannot be specified for operand The following • conflicts limit, not granted. During the wait, the process access state wait access state control attribute When operand 2 is null, is may be modified. This can occur set to allow access state modification. the lock request template identified by operand boundary. The format of operand 1 is 1 if the process' instruction must be aligned on a 16-byte as follows: Chapter 13. Object Lock Management Instructions 13-8 Lock Space Location (LOCKSL) • Number in of space location lock requests Bin(4) template • Offset to lock state selection values Bin(2) • Wait time-out value for instruction Char(8) • Lock request options Char(3) — Reserved (binary — Lock request type — 0 = 1 = Bit 1 Immediate request-lf all locks cannot be immediately granted, signal exception. Synchronous request-Wait until all locks can be granted. Access Bits 2-3 state modifications When - Bit 0 0) the process Bit 2 entering is lock wait for synchronous request: 0= Access 1= Access When - 0= state should not be modified. state should be modified. the process leaving lock wait: is Bit 3 Access state should not be modified. 1 = Access state should be modified. — Reserved (binary — Time-out option 0= Bits 4-5 0) Bit 6 Wait for specified time, then signal time-out exception. 1 = — Reserved (binary — Modify process event = Do not = Modify 0 1 — • Wait indefinitely. Bits 7-15 0) mask modify process event mask process event mask Reserved (binary Bits 17-23 0) Modify process event mask Char(4) control — New process event mask — Previous process event mask UBin(2) • Reserved (binary Char(11) 8 Space The lock UBin(2) 0) Space pointer data object location(s) to be locked This should be repeated as specified by numl 1 Bit 16 option state selection is of lock requests in template above. located by adding the offset to lock state selection values above to operand . • Lock state selection (repeated for each pointer — Char(1) in the template) Bits 0-4 Requested lock state Chapter 13. Object Lock Management Instructions 13-9 Lock Space Location (LOCKSL) = (1 Only one state - - = lock requested, 0 LSRD LSRO LSUP LEAR LENR may be lock not requested) requested. lock Bit lock Bit lock Bit lock Bit lock Bit Reserved (binary 0) Bit Entry active indicator 0 1 = = Bit Entry not active- This entry is not used. Entry active- Obtain this lock. Lock Allocation Procedure: A single Lock Space Location instruction can request the allocation of one or more lock states on one or more space locations. Space location locks are granted sequentially until all the locks requested are granted. The wait time-out field establishes the maximum amount of time that a process competes for the requested set of locks when the lock request type is synchronous. The bits in this field are numbered from 0 to 63, and bit 41 is defined as 1024 microseconds. The maximum wait time-out interval allowed is a value equal to ( 2 « - 1) microseconds. Any value that indicates more time than the maximum wait maximum wait time-out to be used. If the wait time-out field is specified with a then the value associated with the default wait time-out parameter in the process 0, definition template establishes the time interval. time-out causes the value of binary When a requested lock state cannot be immediately granted, any locks already granted by this Lock instruction are released, and the lock request type specified in the lock request tem- Space Location plate establishes the machine action. The lock request type values are described in the following paragraphs. » Immediate Request- If the requested space location locks cannot be granted immediately, this option causes the lock request not grantable (hex 1A02) exception to be signaled. No space location locks are granted, • and the lock request is canceled. Synchronous Request- This option causes the process requesting the locks to be placed in the wait requested locks can be granted. If the locks cannot be granted in the time interval established by the wait time-out field specified in the lock request template, the space location lock wait time-out (hex 3A04) exception is signaled to the requesting process at the end of the interval. No locks are granted, and the lock request is canceled. state until all If the lock request type is synchronous and the requested locks cannot be immediately granted, the access state modification field in the lock request template specifies whether the access state of the process access group is to be modified on entering and/or returning from the lock wait. The parameter has no effect if the process instruction wait access state control attribute specifies that no access state modification is allowed. If the process attribute value specifies that access state modification allowed and the wait on event access state modification option specifies modify access state, the machine modifies the access state for the specified process access group. If the lock request type is synchronous and the invocation containing the Lock Space Location tion is terminated, then the lock request is is instruc- canceled. The modify process event mask option controls the state of the event mask in the process executing When the process event mask is in the masked state, the machine does not schedule signaled event monitors in the process. The event monitors continue to be signaled by the machine or this instruction. other processes. When the process event mask is modified to the unmasked state, event handlers are Chapter 13. Object Lock Management Instructions 13-10 Lock Space Location (LOCKSL) scheduled to handle those events that occurred while the process was masked and those events occurring while If in the unmasked state. the system security level machine attribute is hex 40 or greater and the process is running in user then the modify process event mask option is not allowed and a template value invalid (hex 3801) state, exception is signalled. When the modify process event mask is set to 1, the previous process event mask will be returned and the new process event mask will take effect only when the space location lock(s) have been successfully granted. value is If the space location lock request not returned, nor does the is not successful, the previous process event new process event mask mask take effect. The process event mask values are validity checked only when the modify process event mask Valid masking values are: 1, and ignored otherwise. is set to Masked 256 Unmasked 0 Other values are reserved and must not be specified, otherwise a template value invalid (hex 3801) exception If is signaled. any exception is identified during the instruction's execution, instruction are released, and the lock request is any locks already granted by the canceled. For each space location lock, counts are kept by lock state and by process. When a lock request granted, the appropriate lock count of each lock state specified is incremented by 1. is Exceptions Operands 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 10 parameter reference violation Damage encountered X 04 system object damage state 44 1A partial X system object damage Lock state X 02 lock request not grantable 1C Machine-dependent exception 03 machine storage 06 machine lock 20 Other limit limit X exceeded X exceeded Machine support 02 machine check X 03 function check X Chapter 13. Object Lock Management Instructions 13-11 Lock Space Location (LOCKSL) 02 Exception 22 Object access Operands object destroyed 1 2 X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 32 exceeded X Scalar specification 01 scalar type invalid X 03 scalar value invalid 36 X space extension/truncation X Template specification 01 template value invalid 3A X Space management 01 38 Other X Wait time-out 04 space location lock wait X Chapter 13. Object Lock Management Instructions 13-12 Materialize Data Space Record Locks Materialize Data Space Record Locks (MATDRECL) Op Code Operand (Hex) 032E Operand 1 (MATDRECL) 2 Record selection Receiver template Operand 1: Space pointer. Operand 2: Space pointer. — ILE access MATDRECL ( receiver : se ecti on_templ ate i : space pointer ; space pointer ) Description: This instruction materializes the current allocated locks on the specified data space record. The current lock status of the data space record into the space identified by operand 1. The record selection template record selection template • • is identified by identified by the operand 2 template in operand 2 is materialized must be 16-byte aligned. The format of the as follows. Record selection Char(24) — System pointer Data space identification — Record number — Reserved Char(4) Lock selection Char(8) — Bit 0 Materialize data space locks held 1 0 — = Materialize = Do not materialize Materialize data space locks waited for 1 0 Bit 1 = Materialize = Do not materialize — Reserved Bits 2-7 — Reserved Char(7) The data space identification The record number then Bin(4) all is must be a system pointer a relative record number to a data space. within that data space. locks on the specified data space will be materialized. If If the record the record specified data space a template value invalid (hex 3801) exception is number number is is zero not valid for the signaled. Both of the fields specified under lock selection are bits which determine the locks to be materialized. If the materialize data space locks held is materialize, the current holders of the specified data space record lock are materialized. If the materialize data space locks waited for is materialize, any process waiting to lock the specified data space record is materialized. Chapter 13. Object Lock Management Instructions 13-13 Materialize Data Space Reeord Locks The materialization template materialization is identified by operand 1 (MATDRECL) must be 16-byte aligned. The format of the as follows: ; .1 • Materialization size specification — Number — Number • Char(8) of bytes provided for materialization Bin(4) of bytes available for materialization Bin(4) Materialization data Char(8) — Count of locks held UBin{2) - Count of locks waited - Reserved for UBin(2) j I • Char(4) Locks held identification Char(32) (repeated for each lock held) — Process control space System pointer — Record number Bin(4) — Lock state being described Char(1) Hex CO = DLRD lock state Hex F8 = DLUP lock state other values are reserved. All — 8 Reserved Locks waited for identification (repeated for each lock waited Char(32) for) — Process control space System pointer — Record number Bin(4) - Lock state being described Char(1) Hex CO Hex F8 All The Char(11) = DLRD lock state = DLUP lock state other values are reserved. Reserved Char(11) number of bytes provided for use by the instrucsupplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. tion. first 4 bytes of the materialization identify the total This value is The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length exception described previously. If tion requested, the The count of locks held contains the number of locks held. One system pointer to the process control space (PCS) of each process holding a lock, the relative record number which is locked, and the lock state are materialized in the area identified as locks held identification These fields contain data only if materialize data space locks held is materialize. . The count of locks waited for contains the number of locks being waited for. One system pointer to the process control space (PCS) of each process waiting for a lock, the relative record number and the , Chapter 13. Object Lock Management Instructions 13-14 Materialize Data Space Record Locks lock state which the process identification. These is waitng for are materialized fields contain data only if in (MATDRECL) the area identified as locks waited for materialize data space locks waited for is materialize. Authorization Required • Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands 1 2 01 space addressing violation X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception 06 08 Addressing Argument/parameter 01 0A parameter reference violation Authorization 01 unauthorized for operation 10 X X X X Damage encountered 04 system object damage state X 05 authority verification terminated due to damaged object 44 1A partial X system object damage Lock state X 01 invalid lock state 1C Machine-dependent exception 03 machine storage 20 22 24 Other limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification Chapter 13. Object Lock Management Instructions 1 3-1 5 Materialize Data Space Record Locks (MATDRECL) Operands Exception 01 pointer does not exist 02 pointer type invalid 2E Resource control X X exceeded Scalar specification X X Space management 01 space extension/truncation 38 Other X 01 scalar type invalid 36 2 X limit 01 user profile storage limit 32 1 X X Template specification 01 template value invalid X 03 materialization length exception X Chapter 13. Object Lock Management Instructions 13-16 Materialize Process Locks Materialize Process Locks Op Code Operand (Hex) (MATPRLK) Operand 1 2 Process control Receiver 0312 (MATPRLK) space Operand 1: Space Operand 2: System pointer or pointer. null. ILE access 1 MATPRLK ( receiver var process control spacec space pointer ; system pointer OR null operand ) The lock status of the process identified by operand 2 is materialized into the receiver for the process issuing the specified by operand 1. If operand 2 is null, the lock status is materialized which the process has a for location space object or each identifies instruction. The materialization wait. The format of the asynchronous or synchronous in a lock allocated or for which the process is Description: materialization ® as follows: is Materialization size specification Char(8) - Number of bytes - Number of bytes provided for materialization Bin(4) available for materialization Bin(4) Bin(2) • Number • Expanded number of lock entries Bin(4) » Reserved (binary Char(2) • Lock status (repeated of lock entries 0) for Char(32) each lock currently allocated or waited for by the process) — binary 0 — - System pointer Object, space location, or if or Space pointer no pointer exists Char(1) Lock state - LSRD BitO - LSRO Bit 1 - LSUP Bit 2 - LEAR Bit 3 - LENR Bit 4 - Reserved (binary Bits 5-7 0) Char(1) Status of lock state for process - Reserved Bits 0-1 - Object or space location no longer exists Bit 2 - Waiting because this lock not available Bit 3 - Process in is asynchronous wait Bit 4 for lock Chapter 13. Object Lock Management Instructions 13-17 Materialize Process Locks - Process - Implicit lock (machine-applied) - Lock held by process in Reserved (binary • The synchronous wait for lock (MATPRLK) Bit 5 Bit 6 Bit 7 0) Char(14) 4 bytes of the materialization identify the total number of bytes provided for use by the instrucis supplied as input to the instruction and is not modified by the instruction A value of less than 8 causes the materialization length (hex 3803) exception to be signaled first This value tion. The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver greater than that required to contain the informaNo exce P tions (other than the materialization * length (hex 3803) exception described previously) lenathZx are signaled if the receiver contains insufficient area -^T The number ^ is Unchanged of lock entrie s field identifies the ' number of lock entries that are materialized. When a process holds more than 32,767 locks, this field is set with its maximum value of 32,767. This field has een retained in the template for compatibility with programs using the template prior to the changes 9 made to support materialization of more than 32,767 lock entries. The giegn ded number This field is always set of lock entries field identifies the in addition to the 3 imit number number of lock entries that are materialized of lock entries field described previously however it ° f 32 767 50 * C3n be US6d t0 Specify that more tha " 32.767 locks have t Whe " a process holds more than 32 767 '°cks, the number of lock entries field will eaual 7fiT whi qual 32 32,767, whichh would be incorrect. The expanded number of lock entries field, however will identify the correct number of lock entries materialized. In all cases, this field should be used instead of the number of lock entries field to get the correct count of lock entries materialized. ' ? *°Z ’ ’ ' Authorization Required 8 Retrieve — Context referenced by address resolution Lock Enforcement » Materialize ~ Contexts referenced for address resolution Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 2 X X X X X X X X X X Other Argument/parameter 01 10 1 Addressing parameter reference violation Damage encountered Chapter 13. Object Lock Management Instructions 13-18 Materialize Process Locks (MATPRLK) Operands Exception 04 system object damage state 1 2 Other X X X X 05 authority verification terminated due to damaged object 44 1C partial 22 24 limit X exceeded 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification does not exist 02 pointer type invalid X X X X X 03 pointer addressing invalid object Process state X 02 process control space not associated with a process 2E Resource control limit 01 user profile storage 36 limit X exceeded Space management 01 38 X Machine support 01 pointer 28 X Machine-dependent exception 03 machine storage 20 X system object damage X space extension/truncation Template specification X 03 materialization length exception Chapter 13. Object Lock Management Instructions 13-19 Materialize Process Record Locks Materialize Process Record Locks Op Code (Hex) Operand 031 E Operand /: Space pointer. Operand 2: Space pointer. — 2 Process selection template — ILE access MATPRECL (MATPRECL) Operand 1 Receiver (MATPRECL) ( receiver : sel ecti on_templ ate : space pointer ; space pointer Description: Tiiis instruction materializes the current allocated data space record locks held by the The current lock status of the process identified in the process selection template specified by operand 2 is materialized into the receiver identified by operand 1. The materialization identifies each data space record lock which the process has or the process is waiting process. to obtain. the process control space (PCS) pointer If the instruction is is null or all zeros, the lock activity for the process issuina materialized. The process selection template process selection template is identified by operand 2 must be 16-byte aligned. The format of the as follows: Process selection • - Char(16) Process identification System pointer Lock selection • - 1 0 - Char{8) Materialize held locks Bit 0 = Materialize = Do not materialize Materialize locks waited for 1 0 Bit 1 = Materialize = Do not materialize — Reserved - Reserved Bits 2-7 Char(7) rhe P rocess identification must be a system pointer to a process control space (PCS) or null, all zeros. Both of the fields specified under ock selection are bits j which determine the locks to be materialized the materialize held locks is materialize, any data base record lock held by the process is materialzed lf the materialize lock waited for is materialize any data base record lock the process is waitinq y . ' ' for is materialized. The materialization template materialization » is identified by operand 1 must be 16-byte aligned. The format of the as follows: Materialization size specification — Number Char(8) of bytes provided for materialization Bin(4) Chapter 13 . Object Lock Management Instructions 13-20 Materialize Process Record Locks - Number • • (MATPRECL) Bin(4) of bytes available for materialization Materialization data Char(8) — Count of locks held Bin(2) — Count of locks waited — Reserved Bin(2) for Char(4) Locks held identification (repeated for each lock held) Char(32) — Data space identification System pointer - Relative record — Lock state being described Hex CO Hex F8 All — • number Bin(4) Char(1) = DLRD lock state = DLUP lock state other values are reserved. Char(11) Reserved Locks waited for identification (repeated for each lock waited — Data space identification - Relative record — Lock state being described Hex CO Hex F8 All Char(32) for) System pointer number Bin(4) Char(1) = DLRD lock state = DLUP lock state other values are reserved. — Reserved The first Char{11) 4 bytes of the materialization identify the total number of bytes provided for use by the instrucA value supplied as input to the instruction and is not modified by the instruction. causes the materialization length (hex 3803) exception to be signaled. of less than 8 tion. This value is The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the the byte area identified by the receiver is greater than that required to contain the information requested, the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length (hex receiver. If 3803) exception described previously. The count of locks held contains the number of locks held by the process. One system pointer to the data space relative record number in the data space, and lock state is materialized in the area identiis fied as locks held identification for each lock. These fields contain data only if materialize held locks , materialize. The count number of locks that the process is waiting for. One system number in the data space, and lock state is materialized in of locks waited for contains the relative record pointer to the data space the area identified as locks waited for identification for each lock waited only if materialize locks waited for is materialize. , Chapter 13. for. Object Lock These fields contain data Management Instructions 13-21 Materialize Process Record Locks (MATPRECL) Authorization Required • Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize - Contexts referenced for address resolution Exceptions Operands Exception 06 1 2 X X X X X X 01 X X X X space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 0A parameter reference violation Authorization 01 unauthorized for operation 10 04 system object 44 damage state damaged X X X object X system object damage partial X Lock state 01 invalid lock state 1C X Damage encountered 05 authority verification terminated due to 1 X Machine-dependent exception 03 machine storage limit exceeded 20 X Machine support 02 machine check X 03 function check 22 X Object access 01 object not found X X 02 object destroyed X X X X 03 object suspended 07 authority verification terminated due to destroyed object X 08 object compressed 24 Other Addressing X Pointer specification 01 pointer does not exist 02 pointer type invalid Chapter 13. Object Lock X X X X Management Instructions 13-22 Materialize Process Record Locks (MATPRECL) Operands 1 Exception 2E Resource 01 user profile storage limit 32 Scalar specification X X Space management 01 38 Other X exceeded 01 scalar type invalid 36 2 control limit X space extension/truncation Template specification X 01 template value invalid X 03 materialization length exception Chapter 13. Object Lock Management Instructions 13-23 Materialize Selected Locks Materialize Selected Locks Op Code (Hex) Operand 033 E (MATSEILK) (MATSELLK) Operand 1 Receiver 2 Object or space location Operand 1: Space Operand 2: System pointer or space pointer data pointer. object. —— ILE access MATSELLK ( receiver var system_or_space_pointer : : space pointer pointer ; The locks held by the process issuing this instruction for the object or space location referenced by operand 2 are materialized into the template specified by operand 1. The format of the materialization template is as follows: Description: Materialization size specification — Number — Number Bin(4) of bytes available for materialization Bin(4) Cumulative lock status — for all locks on operand 2 Char(1) Lock state Char(1) LSRD - — Char(8) of bytes provided for materialization - LSRO - LSUP - LEAR - LENR 0 Bit 1 Bit 2 Bit 3 Bit 4 Reserved (binary 0) Bits 5-7 Reserved Number Bit Char(1) of lock entries Bin(2) Reserved Char(2) Lock status (repeated for each lock currently Char(2) allocated) — Lock state Hex Hex Hex Hex Hex All - 80 40 20 10 08 = = = = = Char(1) LSRD lock request LSRO lock request LSUP lock request LEAR lock request LENR lock request other values are reserved Status of lock - Reserved (binary Char(1) 0) Bits 0-5 Chapter 13. Object Lock Management Instructions 13-24 Materialize Selected Locks B| t b Implicit lock - 0 1 = = Not implicit lock implicit lock Is Reserved (binary - (MATSELLK) Bit 7 1) 4 bytes of the materialization identifies the total number of bytes provided for use by the instruction. instruction. This value is supplied as input to the instruction and is not modified by the signaled. to be value of less than 8 causes the materialization length (hex 3803) exception The first A The second 4 bytes of the materialization identifies the total number of bytes available to be materialas the ized. The instruction materializes as many bytes as can be contained in the area specified greater than that required to contain the informathe event that the tion requested, then the excess bytes are unchanged. No exceptions are signaled in receiver contains insufficient area for the materialization, other than the materialization length (hex receiver. If the byte area identified by the receiver is 3803) exception described previously. pointer machine object cannot be specified for operand A space 2. Authorization « Retrieve — Context referenced by address resolution Lock Enforcement: • Materialize — Contexts referenced for address resolution Exceptions Operands 1 2 X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Exception 06 Addressing 01 08 space addressing violation Argument/parameter 01 0A parameter reference violation Authorization X 02 unauthorized for operation 10 Damage encountered X 04 system object 05 authority verification terminated due to 44 1 partial damaged X X X object X system object damage Lock state X 01 invalid lock state 1C Other Machine-dependent exception Chapter 13. Object Lock Management Instructions 13-25 Materialize Selected Locks (MATSELLK) Operands Exception 1 03 machine storage 20 limit Other 2 exceeded X Machine support 02 machine check X 03 function check 22 Object access X \ 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X 03 pointer addressing invalid object 28 X Process state 02 process control space not associated with a process 2E Resource control limit 01 user profile storage limit 32 X exceeded X Scalar specification 01 scalar type invalid 36 X Space management 01 38 X space extension/truncation X Template specification 03 materialization length exception X Chapter 13. Object Lock Management Instructions 13-26 Transfer Object Lock (XFRLOCK) Transfer Object Lock Op Code Operand (Hex) 0382 Operand 1 Operand 2: : System Space — ILE access (XFRLOCK) Operand 2 1 Receiving process Lock transfer control space plate tern' pointer. pointer. — — XFRLOCK ( var recei ving_process_control_space lock_transfer_template : : system pointer space pointer ) The receiving process (operand 1) is allocated the locks designated in the lock transfer template (operand 2). Upon completion of the transfer lock request, the current process no longer Description: holds the transferred lock(s). and the associated lock states that are to be transferred to the receiving process. The space contains a system pointer to each object that is to have a lock transferred and a byte which defines whether this entry is active. If the entry is active, the space also contains the lock states to be transferred. Operand 2 must be aligned on a 16-byte boundary. The format 2 identifies the objects Operand as follows: is Bin(4) template • Number • Offset to lock state selection bytes Bin(2) • Reserved (binary Char(10)* • Object lock(s) to be transferred of lock transfer requests in 0) This should be repeated as specified by The lock state selection is System pointer number of lock transfer requests in template above. located by adding the offset to lock state selection values above to operand 1. • Lock state selection (repeated for each pointer in the template) Char(1) — Bits 0-4 Lock state to transfer. Only one state may be requested. (1 = transfer) - LSRD Bit 0 - LSRO Bit - LSUP Bit 2 - LEAR Bit 3 - LENR Bit — Reserved (binary — Lock count 0 1 1 4 Bit 5* 0) Bit 6 = The current lock count is transferred. = a lock count of 1 is transferred. Chapter 13. Object Lock Management Instructions 13-27 Transfer Object Lock (XFRLOCK) — Entry active indicator 0 = Entry active. 1 Note: If Entry not active. Bit 7 This entry This lock is is not used. transferred. Entries indicated by an asterisk are ignored by the instruction. the receiving process signaled. is issuing the instruction, then no operation The lock count transferred is performed, and no exception either the lock count held by the transferring process or a count of 1. If the receiving process already holds an identical lock, then the final lock count is the of the count originally held by the receiving process and the transferred count. is is sum Only locks currently allocated to the process issuing the instruction can be transferred. If the transfer of an allocated lock would result in the violation of the lock allocation rules, then the lock cannot be transferred. An implicit lock may not be transferred. No locks are transferred if an entry in the template is invalid. The locks specified by operand 2 are transferred sequentially and individually. If one lock cannot be transferred because the process does not hold the indicated lock on the object, then exception data is saved to identify the lock that could not be transferred. Processing of the next lock to be transferred continues. After all event is locks specified in operand 2 have been processed, the object lock transferred (hex 000A,03,01) signaled to the process receiving the locks if any locks were transferred. If any lock was not transferred, the invalid object lock transfer request (hex 1A04) exception is signaled. When an object lock is transferred, the transferring process synchronously loses the record of the lock, and the object is locked to the receiving process. However, the receiving process obtains the lock asynchronously after the instruction currently being executed is completed. If the transferring process holds multiple locks for the object, any lock states not transferred are retained the process. in Authorization Required • Retrieve - Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 06 01 08 1 2 Other Addressing space addressing violation X X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X Argument/parameter 01 parameter reference violation Chapter 13. Object Lock Management Instructions 13-28 Transfer Object Lock (XFRLOCK) Operands 1 Exception Authorization OA Damage encountered 04 system object damage X state X 44 A partial X system object damage X X X 04 invalid object lock transfer request Machine-dependent exception 03 machine storage 20 22 24 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist 02 pointer type invalid X X X X X 03 pointer addressing invalid object 28 Process state X 02 process control space not associated with a process 2E Resource control limit 01 user profile storage limit 36 X exceeded Space management 01 38 X Lock state 01 invalid lock state 1C X X 05 authority verification terminated due to damaged object 1 Other X 01 unauthorized for operation 10 2 X space extension/truncation Template specification X 01 template value invalid Chapter 13. Object Lock Management Instructions 13-29 Unlock Object (UNLOCK) Unlock Object (UNLOCK) ' . Op Code (Hex) Operand 03F1 Unlock template Operand | UNLOCK Space pointer. — ( unlock_template | I 1: ILE access I 1 space pointer : ) Description: The instruction releases the object locks that are specified in the unlock template. The template specified by operand 1 identifies the system objects and the lock states (on those objects) that are to be released. The unlock template must be aligned on a 16-byte boundary. The format is as follows: Number of unlock requests in template Bin(4) Offset to lock state selection bytes Reserved (binary Bin(2) 0) Char(8)* Unlock option Char(1) — Reserved (binary — Unlock type 00 01 10 11 — = = = = 0) Bits 0-3* Bits 4-5 Unlock specific locks now allocated to process Cancel specific asynchronously waiting lock request or allocated locks Cancel all asynchronously waiting lock requests Invalid Reserved (binary Reserved (binary 0) Bit 6-7 0) Char(1) Object to unlock (one for each unlock request) : Unlock options is System pointer located by adding the offset to lock state selection bvtes above to operand Unlock options (repeated for unlock request) — Char(1) Lock state to unlock (only one state can be selected) (1 = unlock) Bits 0-4 LSRD - - LSUP - LEAR 1 = = Bit 3 Bit 4 Bit 5 Lock count reduced by All 1 Bit 2 Lock count option 0 — Bit LENR - — Bit 0 LSRO locks are unlocked. Reserved (binary 1 The lock count is set to 0 Bit 6* 0) Chapter 13. Object Lock Management Instructions 13-30 .. i Unlock Object (UNLOCK) — Bit 7 Entry active indicators 0 1 = = Entry not active. Entry active. This entry is not used. These locks are unlocked. Entries indicated by an asterisk are ignored by the instruction. Note: The unlock type field specifies if locks are to be released or outstanding lock requests are to be canceled. all asynchronous lock waits are being canceled (unlock type specified as 10 ), then objects to unlock and unlock options for each object are not required. If the asynchronous lock fields are provided in the If template, then the data is ignored. Specifying 01 for unlock type attempts to cancel an asynchronous lock request that is identical to the one defined in the template. After the instruction attempts to cancel the specified request, program execution continues just as if 00 had been specified for unlock type. A waiting lock request is canceled corresponding lock states, and if the number of active requests in the template, the objects, the objects match. template all the entries in of the active order the When a lock is released, the lock count is reduced by 1 or set to 0 in the specified state. This option is specified by the lock count option parameter. specified and the unlock count option for an object lock 0 (lock count reduced by 1), then a successful cancel satisfies this request, and no additional locks on the object are unlocked. If the lock count option for an object lock is set to 1 (set lock count to 0), the results of the cancel are disregarded, and all held locks on the object are unlocked. If 01 is specified for unlock type is Specific locks can be unlocked only Implicit locks plate may if is they are allocated to the process issuing the unlock instruction. No locks are unlocked if an entry in the tem- not be unlocked with this instruction. invalid. is Object locks to unlock are processed sequentially and individually. If one specific object lock cannot be unlocked because the process does not hold the indicated lock on the object, then exception data saved, but processing of the instruction continues. requested object locks have been processed, the invalid unlock request (hex 1A03) exception signaled if any object lock was not unlocked. After is If is 01 all is specified for unlock type request (hex 1A03) exception is selected and the cancel attempt is unsuccessful, an invalid unlock signaled when any object lock in the template is not unlocked. is Authorization Required • Retrieve — Contexts referenced for address resolution Lock Enforcement • Materialize — Contexts referenced for address resolution Exceptions Operands Exception 1 Chapter 13. Object Lock Management Other Instructions 13-31 Unlock Object (UNLOCK) Operands Exception 06 Addressing 01 08 space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter 01 0A parameter reference violation X Authorization 01 unauthorized for operation 10 X Damage encountered 04 system object damage state 05 authority verification terminated due 44 1 partial X to damaged X X 24 X Machine-dependent exception 03 machine storage 22 limit exceeded X Machine support 02 machine check X 03 function check X Object access 01 object not found X 02 object destroyed X 03 object suspended X 07 authority verification terminated due to destroyed object X 08 object compressed X Pointer specification 01 pointer does not exist X 02 pointer type invalid 2E Resource control exceeded X Space management 01 38 X limit 01 user profile storage limit 36 X Lock state 03 invalid unlock request 20 X X object system object damage 01 invalid lock state 1C Other 1 space extension/truncation X Template specification 01 template value invalid X Chapter 13. Object Lock Management Instructions 13-32 Unlock Space Location (UNLOCKSL) Unlock Space Location (UNLOCKSL) Op Code Operand Operand 1 Space location or (Hex) 03F2 2 Lock request Unlock template Operand 1: Space pointer data Operand 2: Char(1) scalar or UNLOCKSL ( var spacejocation var lock_request : : object. null. space pointer ; aggregate OR null operand ) When operand 2 is not null, the lock type specified by operand 2 is removed from the space location (operand 1). When the operand 2 is null, the lock type is removed for the space locations specified in the unlock template (operand 1). Description: Any space exist when location(s) specified by 1, or within the template specified by operand 1, need not although the space pointer must be a valid pointer as used to lock operand this instruction is issued the space location. A space pointer machine object cannot be specified The following • when not null: — Bits 0-4 Lock state selection = lock requested, 0 = may be lock not requested) - Only one state - LSRD lock Bit 0 - LSRO lock Bit - LSUP lock Bit 2 - LEAR lock Bit 3 - LENR lock Bit 4 Reserved (binary requested. 1 Bits 5-7 0) space location lock cannot be unlocked because the process does not hold the indicated the invalid space location unlock (hex 1A05) exception When operand 2 is null, Number in is 1 is lock, then signaled. the lock request template identified by operand boundary. The format of operand • 1. Char(1) a the format of operand 2 operand Lock request (1 If is for 1 must be aligned on a 16-byte as follows: of space location unlock requests Bin(4) template • Offset to lock state selection values Bin(2) • Reserved (binary Char(26)* 0) Chapter 13. Object Lock Management Instructions 13-33 Unlock Space Location (UNLOCKSL) • Space location(s) to be unlocked Space pointer This should be repeated as specified by number of space location unlock requests in template above. The unlock options • is located by adding the offset to lock state selection values above to operand Unlock options (repeated for each unlock request) — — = Bits 0-4 = unlock requested, 0 may be unlock not requested) - Only one state - LSRD lock BitO - LSRO lock Bit - LSUP lock Bit 2 - LEAR lock Bit 3 - LENR lock Bit 4 requested. Lock count option = Lock count reduced by 1 = All - Entry active indicator 1 = = 1 locks are unlocked. Reserved (binary 0 (The lock count is set to 0). 0) Entry not active. Entry active. Bit 6 Bit 7 This entry Lock is not used. to be unlocked. is Entries indicated with an asterisk are ignored by the instruction. This instruction can request the deallocation of one or locations. The locks are deallocated sequentially until is 1 Bit 5 0 — Note: Char(1) Lock state to unlock (1 1. deallocated, the lock count is either reduced by specified by the lock count option 1 more all lock states on one or more space specified locks are deallocated. or set to 0 for the specified state. When a lock This option is . Specific locks can be unlocked only if they are held by the process issuing the unlock instruction. If a space location lock cannot be unlocked because the process does not hold the indicated lock, then exception data is saved but processing of the instruction continues. After all requested space location locks have been processed, the invalid unlock request (hex 1A03) exception is signaled if any space location lock No was not unlocked. locks are unlocked if a template value is invalid. Exceptions Operands Exception 06 01 08 i 2 Other Addressing space addressing violation X 02 boundary alignment X 03 range X 06 optimized addressability invalid X Argument/parameter Chapter 13. Object Lock Management Instructions 13-34 Unlock Space Location (UNLOCKSL) Operands Exception 01 10 1 44 1C X partial X Lock state 03 invalid unlock request X 05 invalid space location unlock X Machine-dependent exception 06 machine lock 22 X system object damage 03 machine storage 20 limit limit X exceeded X exceeded Machine support 02 machine check X 03 function check X Object access X 02 object destroyed X X 08 object compressed 24 Pointer specification 01 pointer does not X exist X 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification X 01 scalar type invalid Space management 01 38 X X 03 scalar value invalid 36 Other Damage encountered 04 system object 1A 2 X parameter reference violation X space extension/truncation Template specification X 01 template value invalid Chapter 13. Object Lock Management Instructions 13-35 Exception Chapter 14. Exception This chapter describes alphabetic order. all Management summary of all Instructions Instructions instructions used for exception For an alphabetic Management management. These instructions are in the instructions, see Appendix A, “Instruction Summary.” Materialize Exception Description (MATEXCPD) 14-3 Modify Exception Description (MODEXCPD) Retrieve Exception Data (RETEXCPD) Return From Exception (RTNEXCP) 14-12 Sense Exception Description (SNSEXCPD) 14-15 Signal Exception (SIGEXCP) 14-19 Test Exception (TESTEXCP) 14-24 © Copyright IBM Corp. 1991, 1993 14-6 14-9 14-1 Exception Chapter 14. Exception Management Management Instructions Instructions 14-2 Materialize Exception Description Materialize Exception Description Op Code Operand (Hex) 03D7 Operand 1\ Space Operand 2: Exception description. Operand 3: Character(l) scalar. The Description: (operand 2) into The template option Operand description option instruction materializes the attributes (operand 3) of an exception description by operand 1 1. must be a 16-byte aligned area in the space if the materialization 00. 2 identifies the exception description to be materialized. 3 specifies the materialization option format of the exception description materialization is . If the materialization option bytes provided for materialization Bin(4) bytes available for materialization Bin(4) Char(2) — Bits 0-2 Exception handling action 001 = Do = Do hex 00, the Char(8) Control flags 000 is as follows: Template size — Number of — Number of • 3 Materialization the receiver specified by operand The value of operand • Operand 2 Exception pointer. identified hex is (MATEXCPD) Operand 1 Attribute receiver (MATEXCPD) not handle. (Ignore occurrence of exception and continue processing.) (Disable this exception description and continue to search this invocaanother exception description to handle the exception.) Do not handle. (Continue to search for an exception description by resignaling the exception to the preceding invocation.) Defer handling. (Save exception data for later exception handling.) Pass control to the specified exception handler. not handle. tion for 010 = 100 = = 101 — No data 0 = Exception data 1 = Exception data — Reserved (binary 0) — is returned is not returned 1 = = Reserved (binary — Exception handler type 00 01 10 = = = 4 Bit 5 User data not present User data present — — Bit User data indicator 0 • Bit 3 Bits 6-7 0) Bits 8-9 External entry point Internal entry point Branch point Reserved (binary Instruction number Bits 10-15 0) to be given control UBin(2) Chapter 14. Exception Management Instructions 14-3 Materialize Exception Description (if exception handler type Length of compare value is internal entry point or branch point otherwise, 0) ; (maximum of 32 bytes) Compare value (size established by value length of compare value field) Number Bin(2) of Char(32) of exception IDs Bin(2) System pointer to the exception handling program (if exception handler type is external entry Pointer to user data (not present user data indicator is 0) if Exception ID (one for each exception ID number of exception IDs the materialization option is hex System pointer point) Space pointer value of dictated by the If 01, the Char(2) field) format of the materialization is as follows: Template size • — Number — Number • Char(8) of bytes provided for materialization Bin(4) of bytes available for materialization Bin(4) Control flags Char(2) — Bits 0-2 Exception handling action = Do = Do 000 001 (MATEXCPD) not handle. (Ignore occurrence of exception and continue processing.) not handle. (Disable this exception description and continue to search this invocaanother exception description to handle the exception.) Do not handle. (Continue to search for an exception description by resignaling the exception to the preceding invocation.) Defer handling. (Save exception data for later exception handling.) Pass control to the specified exception handler. tion for 010 = 100 = 101 = - No 0 1 data = = Bit 3 Exception data is returned Exception data is not returned - Reserved If (binary 0) the materialization option • Bit 4-15 is hex 02, the format of the materialization is as follows: Template size — Number of — Number of • Compare value • Compare value The Char(8) bytes provided for materialization Bin(4) bytes available for materialization Bin(4) length (maximum of 32 bytes) Bin(2) Char(32) number of bytes provided for use by the instrucsupplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. tion. first 4 bytes of the materialization identify the total This value is The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exceptions (other than the materialization length (hex 3803) exception) are signaled in the event that the receiver operand contains insufficient area for the materialization. tion requested, then the Chapter 14. Exception Management Instructions 14-4 Materialize Exception Description (MATEXCPD) Exceptions: Operands Exception 06 X 02 boundary alignment X X 03 range X X 06 optimized addressability invalid X X X X space addressing violation parameter reference violation Damage encountered 44 partial damage 22 state system object damage X X X X X X X X Machine-dependent exception 03 machine storage 20 Other Argument/parameter 04 system object 1C 3 X 01 10 2 Addressing 01 08 1 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X X X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control limit 01 user profile storage limit 32 X exceeded Scalar specification X 03 scalar value invalid 36 Space management 01 38 X space extension/truncation Template specification X 03 materialization length exception Chapter 14. Exception Management Instructions 14-5 Modify Exception Description (MODEXCPD) Modify Exception Description Op Code Operand (Hex) 03EF (MODEXCPD) — r » Operand 1 Modifying description butes Operand 1: Exception description. Operand 2: Space pointer or character(2) constant. Operand 3: Character(l) scalar. Description: The exception description attri- 2. Operand references the exception description. Modification option attributes specified by of operand 1 Operand 3 2 Exception operand 3 are modified with the values Operand 2 specifies the new attribute values. Operand 2 may be either a character constant or a space pointer to the modification template. When operand 3 is a constant, operand 2 is a character constant; when operand 3 is not a constant, operand 2 is a space pointer. The value of operand 3 specifies the modification option If the modification option is hex 01 and operand 2 specifies a space pointer, the format of the modifying attributes pointed to by operand . 2 is as follows: - Template size Char(8) - Number of bytes provided for materialization (must be at least - Number - of bytes available for materialization Bin(4)* Control flags - Char(2) Exception handling action = Do = Do 010 = (Ignore occurrence of exception and continue processing.) (Disable this exception description and continue to search this invocation for another exception description to handle the exception.) Do not handle. (Continue to search for an exception description by resignaling the 100 = = exception to the preceding invocation.) Defer handling. (Save exception data for later exception handling.) Pass control to the specified exception handler. 101 not handle. not handle. - No data 0 = Exception data 1 = Exception data — Reserved (binary 0) the exception description present, Bits 0-2 001 000 If Bin(4) 10) Bit 3 is returned is not returned Bits 4-15 was in the deferred state prior to the modification, the deferred signal, if is lost. When the n o date field is set to exception data is not returned, no data is returned for the Retrieve Exception Data or Test Exception instructions, and the number of bytes available for materialization field is set to 0. This option can also be selected in the object definition table entry of the exception description. Chapter 14. Exception Management Instructions 14-6 Modify Exception Description If the modification option of operand 3 is may a constant value of hex 01, then operand 2 character constant. The operand 2 constant has the same format as (MODEXCPD) specify a the control flags entry previously described. If the modification option modification • is hex is 02, then operand 2 must specify a space pointer. The format of the as follows: Template size Char(8) — Number of bytes provided (must be at least 10 plus the length of the compare value - Number of bytes Bin(4) in the exception description) available for materialization Bin(4)* • Compare value length (maximum of 32 bytes) Bin{2)* • Compare value Char(32) Note: Entries shown here The number of bytes in with an asterisk compare value the (*) is exception description as originally specified An are ignored by the instruction. dictated by the in compare value length specified external exception handling program can be modified by resolving addressability to a into the system pointer designated The presence of user data description has user data, is it for the in the the object definition table. new program exception description. not a modifiable attribute of exception descriptions. If the exception can be modified by changing the value of the data object specified in the exception description. Exceptions Operands 06 08 3 01 space addressing violation X X 03 range X X 06 optimized addressability invalid X X X X X X X X X X X X 1 Addressing Argument/parameter 01 10 parameter reference violation Damage encountered 04 system object 44 1C partial damage 22 state system object damage Machine-dependent exception 03 machine storage 20 Other 2 Exception limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X Chapter 14. Exception Management Instructions 14=7 Modify Exception Description (MODEXCPD) Operands Exception 1 03 object suspended 2 3 X X 08 object compressed 24 X Pointer specification 01 pointer does not exist 02 pointer type invalid 2E Resource control X X X X limit 01 user profile storage limit 32 exceeded X Scalar specification 03 scalar value invalid 36 X Space management 01 38 Other space extension/truncation X Template specification 01 template value invalid X 02 template size invalid X Chapter 14. Exception Management Instructions 14-8 Retrieve Exception Data (RETEXCPD) (RETEXCPD) Retrieve Exception Data Op Code Operand (Hex) Operand 1 Operand 1: Space Operand 2: Character(l) scalar. Description: 2 Retrieve options Receiver 03E2 pointer. The data related to a particular occurrence of an exception is returned and placed in the specified space. Operand 1 is a space pointer that identifies the receiver template. The template 1 must be 16-byte aligned in the space. The value retrieved. operand 2 specifies the type The exception handler may be of identified by operand of exception handler for which the exception data is to be a branch point exception handler, an internal entry point exception handler, or an external entry point exception handler. An exception state of process invalid (hex 1602) exception Retrieve Exception Data instruction handling state. if the retrieve option For example, the exception is signaled if is is signaled to the invocation issuing the not consistent with the process's exception the retrieve option specifies retrieve for internal entry point exception handler and the process exception state indicates that an internal exception handler has not been invoked. After an invocation has been destroyed, exception data associated with a signaled exception description within that invocation The format of operand 1 is lost. for the materialization is as follows: Char(8) Template size • — Number of — Number of bytes provided for retrieval Bin(4) bytes available for retrieval Bin(4) Char(2) • Exception identification « Compare value • Compare value Char(32) • Message reference key Char(4) • Exception specific data Char(’) • Source invocation Invocation pointer or Null • Target invocation Invocation pointer • Source invocation address UBin(2) • Target invocation address UBin(2) • Machine-dependent data Char(10) The first length (maximum 4 bytes of the materialization identify the total exception data. This value A of 32 bytes) is Bin(2) number of bytes provided for retrieval of the supplied as input to the instruction and is not modified by the instruction. value of less than 8 causes the materialization length exception (hex 3803) exception to be signaled. The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the Chapter 14. Exception Management Instructions 14-9 Retrieve Exception Data (RETEXCPD) receiver. the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exceptions (other than the materialization length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for If tion requested, then the the materialization. The messa ge reference key field returns the architected value that uniquely identifies the message in the process queue space. The source and source invocation address identify the invocation that caused the exception For machine exceptions, this invocation pointer identifies the invocation executing the exception occurred. For user-signaled exceptions, this invocation pointer locates the invocain vocation to be signaled. when executed the Signal Exception instruction or the Send Process Message instruction. The be null if the source invocation no longer exists at the time that this instruction is executed. The source instruction address field locates the instruction that caused the exception to be signaled. tion that pointer This will field in a bound program invocation will be set to 0. The target invocation and target invocation address identify the invocation that is the target of the the last invocation that was given the chance to handle the exception. For machine exceptions, the first target invocation is the invocation incurring the exception. For usersignaled exceptions, the Signal Exception instruction may initially locate the current or any previous invocation. For Send Process Message, the source and target invocations are specified as input parameters. If the target invocation handles the exception by resignaling the exception, the imme- exception. This invocation is diately previous invocation is considered to be the target invocation. This may occur repetitively until no more prior invocations exist in the process and the signaled program invocation entry is assigned a value of binary 0. If an invocation handles the exception in any manner other than resignaling or does not handle the exception, that invocation is considered to be the target. The target cuted in instruction address field specifies the number of the instruction that is currently being exe- the target invocation. The machine extends the area beyond the exception specific data area with binary pointers to program invocations are aligned on a 16 byte boundary. The operand • - If Hex 00 Hex 01 Hex 02 = = = is set to Exception data Char(1) Retrieve for a branch point exception handler Retrieve for an internal entry point exception handler Retrieve for an external entry point exception handler the exception data retention option retrieval so that the 2 values are defined as follows: Retrieve options - 0's is is set to 1 (do not save), the number of bytes available for 0. always available to the process default exception handler. Exceptions Operands Exception 06 1 2 X X X X Other Addressing 01 space addressing violation 02 boundary alignment 03 range X X 06 optimized addressability invalid X X Chapter 14. Exception Management Instructions 14-10 Retrieve Exception Data (RETEXCPD) Operands Exception 08 01 10 parameter reference violation 2 X X X X X X X X Damage encountered 04 system object damage state 44 16 partial Exception system object damage management X 02 exception state of process invalid 1C Machine-dependent exception 03 machine storage 20 22 limit X exceeded Machine support 02 machine check X 03 function check X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 Pointer specification 01 pointer 2E does not Resource control X exist X exceeded Scalar specification X 03 scalar value invalid 36 Space management 01 38 X limit 01 user profile storage limit 32 Other 1 Argument/parameter X space extension/truncation Template specification X 03 materialization length exception Chapter 14. Exception Management Instructions 14-11 Return From Exception (RTNEXCP) Return From Exception (RTNEXCP) Op Code (Hex) Operand 03E1 1 Return target Operand Space 1: pointer. An internal exception handler subinvocation or an external exception handler invocation terminated, and control is passed to the specified instruction in the specified invocation. All intervening invocations are marked as cancelled, down to, but not including, the invocation that is being returned to. When each of these invocations are returned to, their return handlers and invaocation exit Description: is | | | (l-exit) routines/cancel handlers Note: This instruction | | is will be found and run. not allowed from a bound program invocation. The template identified by operand 1 must be 16-byte aligned in the space. It specifies the target invocation and target instruction in the invocation where control is to be passed. The format of operand 1 is • Invocation address/offset Space/Invocation pointer • Reserved {binary Char(1) • Action | | | as follows: 0) Char(2) - Reserved (binary — Use offset option 0 | 1 = = | - 0) Bits 0-4 Bit 5 Use invocation address as a pointer value Use invocation address as an offset value Unstack option 0 1 = = Bit 6 The action performed If is the exception handler determined by the setting of the following action code (bit 7). an internal exception handler, resume execution with the is instruction that follows the RTNEXCP instruction and terminate the internal exception handler subinvocation. — Action code 0 = 1 = Resume Bit 7 Re-execute the instruction that caused the exception or the instruction that invoked the invocation. tion or execution with the instruction that follows the instruction that caused the excepwith the instruction that follows the instruction that invoked the resume execution invocation. - Reserved (binary Char(1) 0) The invocation address/offset field is a space/invocation pointer that identifies the invocation to which control will be passed. The target invocation address can also be an offset value from the current requesting invocation is done by setting the use offset option field that follows the invocation address field to 1. If the invocation offset value locates the invocation stack base entry, the invocation offset outside range of current stack (hex 2C1A) exception is signaled. If the invocation offset value is a positive number (which represents newer invocations on the stack) a template value field to the invocation to be searched. This invalid (hex 3801) exception is signaled. The current instruction in an invocation is the one that caused another invocation to be created. The un stack option is only valid when issued in an internal exception handler subinvocation and is ignored for an external exception handler invocation. This option will cause the internal exception Chapter 14. Exception Management Instructions 14-12 Return From Exception (RTNEXCP) handler subinvocation to be terminated and control RTNEXCP the instruction. In effect, this option will will resume at the instruction immediately following cause the current subinvocation to be unstacked. addressed invocation is reexecuted, if it is the action code is 0, then the current instruction of the following the current instruction allowed. If the action code is 1, execution resumes with the instruction retry/resume invalid (hex 1604) exception will of the addressed invocation, if it is allowed. If it is not, a If be signaled. invocation of an external The Return From Exception instruction may be issued only from the initial exception handler. internal exception handling sequence or from an invocation that has an active exception handler and has no the instruction is issued from an invocation that is not an external (hex 2C01) exception is siginvalid internal exception handler subinvocations, the return instruction If naled. The following table shows the actions performed by the Return From Exception Addressing Higher Invocation Addressing Issuing Own Instruction Not handling exception Invocation/Option Error (see note 1 Handling internal exception(s) Allowed (see note Handling external exception(s) Error (see note Handling external exception(s) instruction: Invocation/Option Error (sse note 2) 1 Allowed (see note 1 Allowed (see note 3) Allowed (see note 3) Allowed (see note 3) 2) and internal exception(s) Notes: are no more internal excepreturn instruction invalid (hex 2C01) exception is signaled. If there not an external exception handler, the tion handler subinvocations active and this invocation is A 1. may instruction 2. The current 3. All internal exception handler subinvocation is terminated. proceeds within the invocations after the addressed invocation are terminated and execution will be addressed invocation. Any invocation exit programs set for the terminated invocations given control before execution proceeds within the addressed invocation. Whenever an any) An not be issued. is decremented by if is terminated, the invocation count in the corresponding activation entry (if 1. instrucspecifies completion of an instruction rather than execution of the following floating-point a or exception size a signaled the current instruction in the addressed invocation action tion invocation code of 1 inexact result exception. Note: The previous condition does not apply if any of the above exceptions were explicitly signaled by a Signal Exception instruction. A Return From Exception instruction cannot be used or recognized in conjunction with a branch point internal exception handler. If invoke program event a failure to invoke an invocation exit handler occurs, a failure to is signaled. Exceptions Operands 1 Exception 06 Other Addressing Chapter 14. Exception Management Instructions 14-13 Return From Exception (RTNEXCP) Operands Exception 01 X 02 boundary alignment X 03 range X 06 optimized addressability invalid 08 X Argument/parameter 01 parameter reference violation X Damage encountered 10 04 system object 44 16 partial Exception damage state system object damage X x X X management 03 invalid invocation X 04 retry/resume invalid 1C Other 1 space addressing violation X Machine-dependent exception 03 machine storage limit exceeded 20 X Machine support 02 machine check X 03 function check 22 X Object access 02 object destroyed X 03 object suspended X 08 object compressed 24 Pointer specification 01 pointer does not exist X 02 pointer type invalid 2C X Program execution 01 return instruction invalid X 12 activation group access protection violation 1A invocation 2E offset outside Resource control exceeded X Space management 01 38 X limit 01 user profile storage limit 36 X range of current stack space extension/truncation X Template specification 01 template value invalid X Chapter 14. Exception Management Instructions 14-14 Sense Exception Description (SNSEXCPD) Sense Exception Description (SNSEXCPD) Op Code Operand (Hex) Operand 1 Attribute receiver 03E3 Operand 1: Space pointer. Operand 2: Space pointer. Operand 3: Space pointer. Operand 3 2 Invocation tem- Exception template plate in which exceptions are handled for bound programs. This Model (OPM) programs, but can be used against Program instruction is intended for use with Original New Program Model (NPM) bound programs. The data that is returned when an NPM program is accessed will always say that there is an external handler for the sensed exception, that there is no exception data being returned and a starting exception description number of 0. A change has been made Note: in the way The Sense Exception Description instruction searches the invocation specified by specioperand 2 for an exception description that matches the exception identifier and compare value exception the specified in action handling fied by operand 3 and returns the user data and exception Description : The exception descriptions of the invocation are searched Table (ODT) number sequence. description. The template identified by The format of the • attribute receiver 1 is ascending Object Definition must be 16-byte aligned. as follows: Char(8) Template size - Number of bytes - Number of bytes • operand in provided for materialization Bin(4) available for materialization Bin(4) Control flags Char(2) - Bits °’ 2 Exception handling action 000 010 = Do = Do 100 = = not handle- Ignore occurrence of exception and continue processing not handle- Continue search for an exception description by resignaling the excep- immediately preceding invocation Save exception data for later exception handling handlingDefer Pass control to the specified exception handler tion to the 101 — No data 0 = Exception = Exception 1 - Reserved - is returned data is not returned (binary 0) 1 = = 10 = = = 4 Bits 6-7 (binary 0) Bits 8-9 Exception handler type 01 Bit User data not present User data present - Reserved 00 3 Bit 5 User data indicator 0 - data B '* External entry point Internal entry point Branch point Chapter 14. Exception Management Instructions 14-15 Sense Exception Description (SNSEXCPD) - Reserved (binary 0) * Relative exception description * Reserved (binary * Pointer to user data (binary 0 user data indicator is 0) The Bits 10-15 number Bin(2) 0) Char(4) if value of Space pointer 4 bytes of the materialization identify the total number of bvtes provided for use by the instrucis supplied as input to the instruction and is not modified by the instruction A value of less than 8 causes the materialization length (hex 3803) exception to be signaled. first tion. This value The second 4 bytes of the materialization identify the total number of bvtes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exception is signaled in the event the receiver contains insufficient area for the materialization, other than the materialization length (hex 3803) exception described previously. If tion requested, then the The relative exception that °DT the defined des c ription number matched the search determines the value of the index. A value of the ODT matched the search criteria. 8 Invocation address/offset a Search flags | — Use | 0 I 1 I 8 number of the exception 1 definition of the exception descriptions in indicates that the first exception description First is as follows: Space/Invocation pointer Char(2) offset option = = Bit 0 Use invocation address as a pointer value Use invocation address as an offset value - Reserved | the relative The order of in The format of the invocation template | field identifies criteria. (binary 0) Bits 1-15 exception description to search Bin(2) The template | | \ | identified by operand 2 must be 16-byte aligned. The invocation addr ess /nffc Pt field is a space/invocation pointer that identifies the invocation to be searched. The invocation is searched for a matching exception description. If the invocation address locates either an invalid invocation or the invocation stack base entry, the invalid invocation address (hex 1603) exception is signaled. The invocation address/ offset field can also be an offset value from the current requesting invocation to the invocation to be searched. This is setting the use offset option bit field that follows the invocation address field to 1. If the invocation offset value locates the invocation stack base entry, the invocation offset outside range of current stack (hex 2C1A) exception is signaled. If the invocation offset value is positive or zero, a template value invalid (hex 3803) exception is signaled. ?* except. °n descript iorLtoêarch held specifies the relative number of the exception description used to start the search. The number must be a nonzero positive binary number determined by he order of definition of exception descriptions in the ODT. A value of 1 indicates that the first exception description in the invocation is to be used to begin the search. If the value is greater than the number of exception descriptions for the invocation, the operand 1 template is materialized with the ill to be number of bytes available for materialization set to 0. The operand 3 exception template specifies the exception-related data ment. The format of the template is as follows: * to be used as a search argu- Template size Char(8) Chapter 14. Exception Management Instructions 14-16 Sense Exception Description (SNSEXCPD) - Number (must be at least 44) — Number of Exception identifier • Compare value • Compare value length (maximum Hex nnOO nnmm = Bin(2) of 32) Char(32) are ignored by the instruction. {*) identifier in the exception description = Any exception = Any exception Hex 0000 Hex Char(2) Entries noted with an asterisk The exception Bin(4)* bytes available for materialization » Note: Bin{4) of bytes provided for materialization ID will result in a nn ID in class Only exception ID nnmm can be specified one of the following ways: in match will result in will result in a match a match a match on exception ID is detected, the corresponding compare values are matched. If the compare value length in the exception description is less than the compare value in the search template, the length of the compare value in the exception description is used for the match. If the compare value length in the exception description is greater than the compare value in the search template, an autoIf matic mismatch results. match on exception ID and compare value is detected, the exception handling action of the exception description determines which of the following actions is taken: If a IGNORE The operand template 1 DISABLE The exception materialized. is description bypassed and the search is for an exception description continues with the next exception description defined for the invocation. RESIGNAL The operand 1 template materialized. is The operand 1 template is materialized. HANDLE The operand 1 template is materialized. DEFER no exception description of the invocation matches the exception ID and compare value of operand the number of bytes available for materialization on the operand 1 template is set to 0. If 3, Exceptions 12 Operands Exception 06 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 Argument/parameter 01 10 parameter reference violation Damage encountered damage X system object damage X 04 system object 44 16 Other XXX XXX XXX XXX XXX Addressing 01 3 partial Exception management Chapter 14. Exception Management Instructions 14-17 Sense Exception Description (SNSEXCPD) Operands Exception 2 1 03 invalid invocation address 1C Other 3 X Machine-dependent exception 03 machine storage 20 limit exceeded X Machine support 02 machine check X 03 function check 22 X Object access xxx xxx xxx xxx xxx 01 object not found 02 object destroyed 03 object suspended 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Program execution 1 2E A invocation offset outside range of current stack Resource control X limit 01 user profile storage limit 32 exceeded X Scalar specification xxx 01 scalar type invalid 36 Space management 01 38 X space extension/truncation X Template specification 01 template value invalid X 02 template size invalid X X 03 materialization length exception X Chapter 14 . Exception Management Instructions 14-18 Signal Exception (SIGEXCP) Signal Exception (SIGEXCP) Op Code Operand Extender (Hex) SIGEXCP 10CA Operand 1 Operand 2 Attribute template Exception data 3-4 SIGEXCPB 1CCA Branch options Attribute template Exception data Branch targets SIGEXCPI Indicator options Attribute template Exception data Indicator targets 18CA Operand 1: Space pointer. Operand 2: Space pointer. Operand 3-4: Branch Form - Branch number. • Form-Numeric variable scalar or character variable Indicator • point, instruction pointer, relative instruction instruction signals a The Signal Exception Description: number, or absolute instruction scalar. new exception or resignals an existing excep- one of the specified targets based on the tion to the process. Optionally, the instruction branches to extender field, or it sets indicators based the results of the signal and the selected branch options in identified in the signal on the results of the signal. The signal is presented starting at the invocation template. AddiThe SIGEXCP instruction is a subset of the Send Process Message (SNDPRMSG) instruction. instruction SIGEXCP the when defaulted be tional parameters used in the SNDPRMSG instruction will information about the complete set of parameters is used. See the SNDPRMSG instruction for more available when signalling an exception. The template aligned • • in identified by operand 1 specifies the signal option and starting point. Space/Invocation pointer Char(1) Signal option 1 - Bit 0 Signal/resignal option 0 must be 16-byte the space with the following format. Target invocation address - It = = Signal new exception. Resignal currently handled exception (valid only for an external exception handler). Invoke PDEH (process Bit default 1 exception handler) option 0 1 = Invoke PDEH no exception description found for invocation. = Do not invoke PDEH no exception description found for invocation if if (ignore if base invocation entry specified). — 0 1 — • Bit 2 Exception description search control = = Exception description search control not present Exception description present Reserved (binary Reserved (binary Bits 3-7 0) Char(1) 0) Chapter 14. Exception Management Instructions 14-19 Signal Exception (SIGEXCP) • I | | i | First exception description to search Bin(2) Tlie tar g et invocation signalled. address pointer uniquely identifies the invocation to which the exception is to be Signalling directly to the PDEH can not be accomlished via this instruction. Support function being provided for this is in the SNDPRMSG instruction. the target invocation address pointer locates neither a valid invocation entry nor the base invocation entry, the invalid invocation (hex 1603) exception is signaled. If The invocation which issued j | | this instruction will be checked to ensure it has the proper authority to send an exception message to the target invocation. If the authority check fails, activation group access violation (hex 2C12) will be signaled. If the program associated with the invocation has defined an exception description to handle the exception, the specified action | | | | | | invoked unless the invoke cation entry PD EH optio n (the exception is taken; otherwise, the considered ignored). addressed instead of an existing invocation, the PDEH will be invoked. is bit is 1 is If PDEH is the base invo- A change has been made to the way in which exception handlers are determined The following description relates only to the invocation of exception grams. In for bound programs. handlers related to OPM proboth instances the actions of signalling and handling have been broken apart. Note: Exception descriptions of an invocation are searched in ascending ODT number sequence. If the inception desc ripti on search control control specified that an exception description is not present the search begins with the first exception description defined in the ODT. Otherwise, the first exception description to search value identifies the relative number of the exception description to be used to start the search. The value must be a nonzero positive binary number determined by the order of definition of exception descriptions in the ODT. This value is also returned by the Sense Exception Description instruction. A value of 1 indicates that the first exception description in the invocation is to be used to begin the search. If the value is greater than the number of exception descriptions for the invocation, the template value invalid (hex 3801) exception is signaled. , an exception ID in an exception description corresponds to the signaled exception, the corresponding co mpare values are verified. If the compare value length in If the exception description the signal template, the length of the compare value in the exception description is used for the match. If the compare value length in the exception description is greater than the compare value length in the signal template, an automatic mismatch results. Machine-signaled exceptions have a 4-byte compare value of binary 0's. is less than the compare value length in An exception description may monitor Hex 0000 = Any signaled exception Hex nnOO Hex = Any nnmm = for an exception with a generic ID results in a signaled exception ID The signaled exception in ID ID as follows: match. class nn results must be exactly in a match. nnmm in order for a match to occur. An exception description may be in one of five states, each of which determines an action to be taken when the match criteria on the exception ID and compare value are met. IGNORE No exception handling occurs. The Signal Exception instruction is assigned a resultant condition of ignored. If a corresponding branch or indicator setting is present, that action takes place. DISABLE The exception description is bypassed, and the search for a monitor continues with the next exception description defined for the invocation. Chapter 14. Exception Management Instructions 14-20 Signal Exception (SIGEXCP) for a monitoring exception description is to be reinitiated at the preceding invocation. A resignai from the initial invocation in the process results in the invocation of the process default exception handler. A resignal from an invocation exit program results in an unhandled exception that causes process termination. RESIGNAL The search signaled, and the Signal Exception instruction is assigned the resultant condition of deferred. If a corresponding branch or indicator setting is present, that action takes place. To take future action on a deferred excep- DEFER The exception description tion, is the exception description must be synchronously tested with the Test Exception instruction in the signaled invocation. passed to the indicated exception handler, which may be a branch internal subinvocation, or an external invocation. HANDLE Control is point, an instruction is in the ignore or defer state and if the Signal Exception if it specifies branch or indicator conditions condition or indicator branch or specify a not does executed. that are not met, then the instruction following the Signal Exception instruction is If the exception description given to an internal or branch point exception handler, all invocations up to, but programs not including, the exception handling invocation are terminated. Any invocation exit proceeds in the sigexecution before control given be will invocations terminated set for the When control is naled exception handler. When this instruction is invoked with the Resignal option, all invocations up to, but not including, the message is signalled to the next oldest invocation in the (RTNEXCP) instruction can no longer return to the Exception from Return that the stack. This implies handlers set for the cancelled invocations will cancel Any request. resignal invocation that issued the interrupted invocation are cancelled and the be given control before execution proceeds in the signaled exception handler. to invoke a failure to invoke an external exception handler or an invocation exit occurs, a failure corresponding the count in invocation the invocation, destroyed each For program event is signaled. If activation entry (if any) is decremented by 1. operand 2 must be 16-byte aligned in the space. It specifies the exceptionthe exception signal. The format of the exception data is the same as with passed related data to be Data instruction. The format is as follows: Exception that returned by the Retrieve The template identified by Char(8) Template size — Number of Bin(4) bytes of data to be signaled (must be at least 48 bytes) — Number Bin(4)* of bytes available for materialization Char(2) Exception identification Compare value length (maximum Bin of 32 bytes) Char(32) Compare value Char(4)* Reserved Char(*) Exception specific data Note: Entries (2) shown here with an asterisk (*) are ignored by the instruction. resignal because the exception-related data is the a as for the exception currently being processed; however, it must be specified when signaling Operand 2 is ignored \t signal! resignal option is same new exception. The maximum size for exception specific data that is to Exception instruction is accompany an exception signaled by the Signal 65 503 bytes, including the standard exception data. Chapter 14. Exception Management Instructions 14-21 Signal Exception (SIGEXCP) The following required parameters only available on the | SNDPRMSG lowing default values: Message Initial status - Log message monitor priority Interrupt class mask Source invocation - - - + Retain + instruction will be qiven the fol- Action pending 64 Message generated by invocation issuing Signal Exception instruction SIGEXCP instruction Resultant Conditions * Exception ignored • Exception deferred. Authorization Required: The invocation which originated the exception must have proper activation group access to the target invocation. The following algorithm is used to determine this access. 1. The invocation which invoked the SIGEXCP instruction must have access as the Originating Invocation. fied to the invocation identi- 2. The Originating Invocation must have access to the invocation identified as the Source Invocation or to the invocation directly called by the Source invocation. 3. The Originating Invocation must have access to the invocation identified as the Target Invocation or to the invocation directly called by the Target Invocation. If any of the access checks fail then an activation group access violation {hex 2C12) exception will signaled. be Exceptions Operands Exception 06 01 space addressing violation 02 boundary alignment 03 range 06 optimized addressability invalid 08 parameter reference violation Damage encountered 04 system object 44 16 2 X X X X X X X X X X partial Exception damage XXX xxx state system object damage management 02 exception state of process invalid X 03 invalid invocation 1C X Machine-dependent exception 03 machine storage 20 Other Argument/parameter 01 10 1 Addressing limit exceeded X Machine support 02 machine check X Chapter 14. Exception Management Instructions 14-22 Signal Exception (SIGEXCP) Operands 1 Exception 03 function check 22 2 X Object access 01 object not found X X 02 object destroyed X X 03 object suspended X X X 08 object compressed 24 Pointer specification 01 pointer does not exist 02 pointer type invalid 2C Resource control X X X X exceeded Space management 01 38 X limit 01 user profile storage limit 36 X Program execution 12 activation group access violation 2E Other X space extension/truncation Template specification 01 template value invalid X 02 template size invalid X Chapter 14. Exception Management Instructions 14-23 Test Exception (TESTEXCP) Test Exception (TESTEXCP) Op Code (Hex) TESTEXCP Extender Operand Operand 1 Receiver 104A description TESTEXCPB Branch options Receiver Exception 1C4A Branch options description TESTEXCPI 184A Indicator options Receiver Exception 1 Operand 2: Operand 3-4: Space : pointer. Exception description. Branch Form - Branch number. Indicator point, instruction pointer, relative instruction Form-Numeric variable scalar or character variable number, or absolute instruction scalar. The instruction tests the signaled status of the exception and optionally alters the control flow or sets the specified indicators data is returned at the location identified by operand 1. The branch or on the conditions specified in the extender field depending on whether Description: 2, description Operand is 2 is signaled only Operand 1 an exception description whose signaled status if the referenced exception description addresses a space The template description specified based on the in operand Exception indicator setting occurs based or not the specified exception into is in is to be tested. identified which the exception data by operand is must be 16-byte aligned 1 placed in if an exception identified by the the space and is formatted as follows: Char(8) — Number of bytes — Number of bytes provided for materialization Bin(4) available for materialization Bin(4) exception description is not signaled) Exception identification Compare value An exception can be the deferred state. Template size if test. signaled. exception description has been signaled. (0 Indicator options description Operand • Operand 3-4 2 Exception length Char(2) (maximum of 32 bytes) Bin{2) Compare value Char(32) Message reference key Char(4) Exception-specific data Char{*) Source invocation address Invocation/Null pointer Target invocation address Invocation pointer Signaling program instruction address UBin(2) Signaled program instruction address UBin(2) Machine-dependent data Char(10) Chapter 14. Exception Management Instructions 14-24 Test Exception (TESTEXCP) 4 bytes of the materialization identify the total number of bytes provided for use by the This value is supplied as input to the instruction and is not modified by the instruction. value of less than 8 causes the materialization length (hex 3803) exception to be signaled. The first A instruction. The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the informaexcess bytes are unchanged. No exceptions (other than the materialization tion requested, then the length (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for the materialization. the exception description If materialization entry is is not in the signaled state, the set to binary 0's, number The message reference key field holds the architected value message in a process queue space. The source invocation address when this instruction is field will that uniquely identifies the exception contain a null pointer if the source invocation no longer exists executed. The area beyond the exception-specific data area program invocations are properly aligned. is extended with binary no branch options are specified, instruction execution proceeds If of bytes available for the and no other bytes are modified. 0's so that pointers to at the instruction following the Test Exception instruction. the exception data retention option, from the exception description, If is set to 1 (do not save), no data returned by this instruction. is Resultant Conditions • Exception signaled ° Exception not signaled. Exceptions Operands 06 X X X X X X 03 range X 06 optimized addressability invalid X Argument/parameter X parameter reference violation Damage encountered 04 system object damage state 44 16 X X space addressing violation 02 boundary alignment 01 10 Other Addressing 01 08 2 1 Exception partial Exception system object damage management X 01 exception description status invalid 1C Machine-dependent exception Chapter 14. Exception Management Instructions 14-25 Test Exception (TESTEXCP) Operands Exception 1 03 machine storage 20 limit 2 exceeded Machine support 02 machine check X 03 function check 22 X Object access 08 object compressed 24 X Pointer specification 01 pointer does not exist X 02 pointer type invalid 2E Resource control exceeded X Space management 01 38 X limit 01 user profile storage limit 36 Other X space extension/truncation X Template specification 03 materialization length exception X Chapter 14. Exception Management Instructions 14-26 Queue Space Management Chapter 15 . Queue Space Management Instructions Instructions This chapter describes the instructions used for queue space management. These instructions are alphabetic order. For an alphabetic summary of all the instructions, see Appendix A, “Instruction in Summary.” Materialize Process © Message (MATPRMSG) Copyright IBM Corp. 1991, 1993 15-3 15-1 Queue Space Management Chapter 15. Queue Space Management Instructions Instructions 15-2 Materialize Process Materialize Process Message (MATPRMSG) Message (MATPRMSG) I Op Code Operand (Hex) 039C Operand 2 Message template 1 Materialization Operand 3 Source template Operand 4 Selection template template Operand /: Space pointer Operand 2: Space pointer Operand 3: Space pointer or Operand 4\ Space pointer null ilx access MATPRMSG ( recei ver_templ ate message_template source_template space pointer ; space pointer ; space pointer ; OR null operand selection_template ; space pointer A message is materialized from a queue space according to the options specified. The located on a queue space queue specified by operand 3. The message is selected by the operand 4 criteria. Operands 1 and 2 contain the materialized information from the process message. Description: message is The template identified by operand 1 must be 16-byte aligned. Following is the format of the materialization template: Template size specification Char(8)‘ — Number of — Number of bytes provided for materialization Bin(4) bytes available for materialization Bin{4) Process queue space queue offset Bin(4) Reserved (binary Char(4) 0) Time sent Char(8) Time modified Char(8) Interupted invocation Invocation pointer Invocation pointer, or Target invocation System pointer Original target invocation Invocation pointer Source program location Suspend pointer Target program location Suspend pointer Originating program location Suspend pointer Invocation mark Activation group Reserved (binary UBin(4) mark UBin{4) Char(8) 0) Chapter 15. Queue Space Management Instructions 15-3 Materialize Process The first Message (MATPRMSG) 4 bytes of the materialization template identify the total number of bytes provided for use by supplied as input to the instruction and is not modified by the instruction. If the value is zero for this field, then the operand 1 template is not returned. A number less than 128 (but not 0) causes the materialization length (hex 3803) exception. the instruction. number This Queue space queue is offset This value indicates which be returned will message log. If if queue in the queue space a message resides on. A value of-1 message is on the external queue, and zero if the message is on the message resides on an invocation queue this field will be zero. the the Time sent The value of the system time-of-day clock when the message was originally sent (Send Process Message instruction, Signal Exception, or message originated as a result of an exception). Time modified This value is initially equal to the time sent value. However, it can be modified by the Modify Process Message instruction. Interrupted invocation An invocation pointer that addresses the invocation which currently has this message as This pointer is null if the message is not an exception message. its interrupt cause. Target invocation An invocation pointer or system pointer that identifies which queue contains the message. message resides on an invocation queue, this field contains an invocation pointer that addresses the invocation whose invocation message queue currently contains the message. If the message does not reside on an invocation queue, then a system pointer to the Queue Space is returned. The queue space queue offset field indicates which queue on which the message resides, the message log or the external queue. If the Original target invocation An invocation pointer that addresses the invocation which originally is null if the original target invocation no longer exists. was sent the message. This pointer Source program location A suspend pointer which program, module, procedure, and statement where to a CALL or some form of interrupt). If the message was originally sent as a non-interrupt message, then the source invocation is the one identified by the Send Process Message instruction, and the suspend point identified is the source invocation identifies the was suspended (due the one that tion is was current when that instruction was executed; otherwise the source invocathe invocation for which the message was most recently an interrupt cause. Target program location A suspend pointer which identifies the program, module, procedure, and statement where was suspended (due to a CALL or some form of interrupt). If the the target invocation message is no longer in an invocation message queue, then this pointer reflects the invoca(most recent) invocation message queue in which the message resided. This tion of the last pointer is null if the message has never resided in an invocation message queue. Originating program location A suspend pointer which identifies the program, module, procedure, and statement of the instruction that sent the message. For messages sent by the machine, this pointer area contains a machine-dependent representation of the source Send Process Message machine component. Invocation mark If the mark message has ever resided on an invocation, this field will be non-zero. where the message was last queued. It contains the of the invocation Chapter 15. Queue Space Management Instructions 15-4 Message (MATPRMSG) Materialize Process mark message has ever resided on an Activation group the If mark invocation, this field will be non-zero. It contains the where the message was of the activation group which contains the invocation last queued. The template identified by operand 2 is used to contain the materialized message. It must be 16-byte aligned with the following format. • Template size — Number — Number • of bytes provided for materialization Bin(4) of bytes available for materialization Bin(4) Message type Char(1) — hex 00 = Informational message 0 — hex 01 = Informational message — hex 04 = Exception message — hex 06 = Return/Transfer Control message — hex 07 = Return message All other values are reserved. • Reserved (binary • Message • Reply/Inquiry 3 Message — 1 severity Bin(2) message reference key status Char{4) mask Char(8) Bit 0 = The message = The message is is not queued to the Process Message Log. queued to the Process Message Log. Inquiry 0 1 — Char(1) 0) Log message 0 — 1 Bit = Message = Message will not accept a reply. will accept a reply. Reply 0 1 Bit 2 = Message does not represent a reply message. = Message represents a reply message. — Answered 0 1 = Bit 3 messages For with a status of inquiry this indicates that a reply message has with a status of inquiry, this indicates that a reply message has been not been received. 1 = messages For received. — Message 0 1 = = being processed Bit 4 This value of the flag has no particular meaning. For a message type of exception, this indicates that the interrupt is currently being handled. — Retain 0 = Message bits 1 Bit 5 = will be dequeued and its contents discarded when the following message status are FALSE: Log, Message being processed, and Action pending. Keeps the message from being dequeued after all Chapter other 15. message status bits are FALSE. Queue Space Management Instructions 15-5 Materialize Process - Action pending 0 1 = = Message (MATPRMSG) Bit 6 Indicates no actions are pending based on this message. Indicates that the message is either an interrupt cause or is a Return, Return/Transfer Control message. - Invoke Process Default Exception Handler (PDEH) 0 1 — = Do not = Invoke Bit 7 invoke PDEH. PDEH, only valid if message type is exception. Error 0 1 Bit 8 = No = An — PDEH 0 1 error has occurred in the sending of this message. error has occurred in the sending of this message. previously invoked = PDEH = PDEH Bit 9 has not previously been invoked for this message. has previously been invoked for this message. - Reserved (binary 0) - User defined status Interrupt class — - - - Bits 10-31 Bits 32-63 mask Char(8) Binary overflow or divide by zero Bit 0 Decimal overflow or divide by zero Bit 1 Decimal data error Bit 2 Floating-point overflow or divide by zero Bit 3 Floating-point underflow or inexact result Bit 4 Floating-point invalid operand or conversion error Bit 5 Other data error Bit 6 (edit mask, etc) Specification (operand alignment) error Bit 7 - Pointer not set/pointer type invalid Bit 8 - Object not found Bit 9 Object destroyed Bit 10 - - Address computation underflow/overflow - Space not allocated as specified offset - Bit 12 Domain/State protection violation Bit 13 Authorization violation Bit 14 - Reserved (binary 0) — Other Ml generated — Bit 11 Bit 15-28 exception (not function check) Bit 29 Ml generated function check/machine check - Message generated by Signal Exception - Send Process Message instruction - Send - Send - Send - Send Bit instruction 30 Bit 31 Bit 32 Process Message instruction Bit 33 Process Message instruction Bit Process Message instruction Bit 35 Process Message instruction Bit 36 Chapter 15. 34 Queue Space Management Instructions 15-6 Materialize Process — Send - Send Message (MATPRMSG) Process Message instruction Bit Process Message instruction Bit 38 — Send Process Message — User defined 37 Bit 39 instruction Bits 40-63 handler priority Char(1) Q Initial a Current handler priority Char(1) « Exception ID UBin(2) 0 PDEH Reason Code Char(1) o Reserved (binary Char(1) 0 Compare data length Bin(2) 0 Message ID Char(7) 0 Reserved (binary Max message 0 0) Char(1) 0) 0 Message data length 0 Max message extension data 0 Message extension data 0 Message data 0 Message data extension 0 Message format information — length of If Bin(4) 1 Bin(4) length is pointer message the is 1 Space pointer 1 not a return or return/transfer control message. Char(32) a return or return/transfer control message. System or Return handler identifier - Space pointer Char(32) Compare data - - Bin(4) pointer message the If Bin(4) 1 data length Procedure pointer Reserved - Reserved (binary 0 The first Char(16) Char(32) 0) messaae template identify the total number of bytes provided for use the number is supplied as input to the instruction and is not modified by the instruction 4 bvtes of the instruction. A number This less than 160 causes the materialization length (hex 3803) exception. Message type This value determines the type of the message. The type of message The following message status are • Log Message Reply • Inquiry • The following message status are • i message determines which status values have meaning. valid for all valid for a informational message type message types. of Exception. Log Message Input to the instruction Chapter 15. Queue Space Management Instructions 15-7 Message (MATPRMSG) Materialize Process • Retain • Action pending • Invoke • Inquiry • Reply PDEH The following message status are valid for a message type of return or return/transfer control. Action pending • The following describes each message type in detail. • Informational 0 - There are no special requirements as to what or what the Target Invocation pointer actually identifies. message status contains • Informational message status contains • Exception • Return 1 - There are no special requirements as to what or what the Target Invocation pointer actually identifies. - message type This invocation message has an This type of - is interrupt cause for the interrupeted invocation. indicates that a return handler will be invoked exited for any reason other than Transfer Control (XCTL). XCTL, the message In if the target the case of preserved and associated with the transferred to invocation. of this type interpret the message format information field to identify a program or procedure to be invoked as the return handler. Additionally, • is messages This message type indicates that a return handler is invoked the target invocation is exited for any reason including XCTL. Additionally, messages of this type interpret the message format information field to identify a program or Return/Transfer control - when procedure to be invoked as the return handler. Message severity A value indicating the severity of the message. message reference key message materialized is an inquiry message, message reference key of its reply message. Replv/lnquirv If the If the message materiali

AS400 MI Functional Reference-SC41-8226-02 text

Related documents

Products

Support

AS400 MI Functional Reference-SC41-8226-02 text

Related documents

Add this document to collection(s)

Add this document to saved

Suggest us how to improve StudyLib