Open PL/I Built-ins

Built-in functions and subroutines are procedures provided by the Open PL/I language. They can be used wherever an expression is valid.

The built-in functions and subroutines provided by Open PL/I can be grouped into the following classes:

• Arithmetic built-in functions, which do one of the following:
  • Provide information about the properties of arithmetic values
  • Perform ordinary arithmetic calculations
  • Manipulate variables with a specified precision, returning the value resulting from the operation.

  These include:

  ABS CEIL FLOOR INT MAX MAXEXP MAXVAL MIN MINVAL MOD MULTIPLE

  POSINT RADIX RANDOM ROUND ROUNDAWAYFROMZERO ROUNTTOEVEN SCALE SCALEVAL SIGN TRUNC

• Array-handling built-in functions, which provide information about arrays and array elements. These include:

  ABS ALL ANY BOOL CENTERLEFT CENTERRIGHT DIMENSION HBOUND LBOUND LEFT

  LOWERCASE PROD REVERSE RIGHT SUBSTR SUM TRANSLATE TRIM UPPERCASE

• Buffer-management built-in functions, which operate on an area of storage specified by an address and a number of bytes known as a buffer. These include:
  • COMPARE
  • HEXDECODE
  • HEXIMAGE
  • PLIFILL
  • PLIMOVE
  • PLIOVER
  • XMLCHAR
  • XMLSCRUB
• Condition-handling built-in functions, which provide information about interrupts that are caused by signaled conditions. Use the condition-handling built-in functions to determine the cause of a condition that has occurred. These functions can only be used within the scope of an ON-unit or dynamic descendant for the condition specific to the built-in function, or the ERROR or FINISH condition when raised as an implicit action. All other uses are out of context.

  Condition-handling built-in functions include:

  • DATAFIELD
  • ONCHAR
  • ONCODE
  • ONCONDID
  • ONFILE
  • ONKEY
  • ONLOC
  • ONSOURCE
  • ONSUBCODE
• Date/time built-in functions. These functions return or manipulate date and time information in terms of days, seconds, and character date/time stamps. Some of date/time built-in functions allow you to specify the date/time patterns to be used. The time zone and accuracy for these functions are system dependent. Date/time built-in functions include:

  DATE DATETIME DAYS DAYSTODATE DAYSTOSECS REPATTERN

  SECS SECSTODATE SECSTODAYS TIME TIMESTAMP VALIDDATE WEEKDAY

• Floating-point inquiry built-in functions, which return information about specified floating-point variable arguments. These include:

  EPSILON EXPONENT HUGE ISFINITE ISINF ISNAN ISNORMAL

  ISZERO MAXEXP PLACES PRED SUCC TINY

• Input/output built-in functions, which determine the current state of a file. These built-in functions include:
  • COUNT
  • ENDFILE
  • FILEDDWORD
  • FILEDDINT
  • FILEOPEN
  • FILEREAD
  • FILEWRITE
  • LINENO
  • PAGENO
  • SAMEKEY
• Integer manipulation built-in functions. These functions perform operations on integer variables and return the result of the operation. These include:
  • IAND
  • IEOR
  • INOT
  • IOR
• Mathematical and trigonometric built-in functions, which perform standard mathematical calculations in floating-point. Any argument that is not floating-point is converted. These built-ins include:

  ACOS ASIN ATAN ATAND ATANH COS COSD COSH ERF ERFC EXP

  LOG LOG10 LOG2 SIN SIND SINH SQRT SCALEVAL TAND TANH

• Miscellaneous built-in functions and subroutines. These include:

  COLLATE FLUSH HEX INLIST LPIPARAMCOUNT OMITTED PACKAGENAME PLIDUMP PLIRETC PLIRETV PLISAXA PLISAXB

  PLISAXC PLISRTx PLITEST SQRT PRESENT REPLACE RESIGNAL SOURCEFILE SOURCELINE STRING TALLY UNSPEC

• Precision-handling built-in functions, which manipulate variables with specified precisions, and return the value resulting from the operation. These include:
  • ADD
  • BINARY
  • DECIMAL
  • DIVIDE
  • FIXED
  • FIXEDBIN
  • FIXEDDEC
  • FLOAT
  • FLOATBIN
  • FLOATDEC
  • MULTIPLY
  • PRECISION
• Preprocessor built-in functions, which are invoked in the same way that programmer-defined functions are invoked, except that they must be invoked with the correct number of arguments. See the topic Preprocessor Built-In Functions for more information.
• Pseudovariables. These can appear only:
  • on the left side of an assignment statement
  • as the target in a DO-specification and then only if it is one of SUBSTR, REAL, IMAG or UNSPEC
  • in the data list of a GET statement or in the STRING option of a PUT statement
  • as the string name in a KEYTO or REPLY option.
  These include:
  • STRING
  • SUBSTR
  • UNSPEC
• Conversion built-in functions, which convert data from one data type to another. These include:
  • BINARYVALUE
  • BYTE
  • CHARACTER
  • RANK
• Storage-handling built-in functions, which provide information on the storage requirements and location of variables. These include:

  ADDR ADDRDATA ALLOCATION AUTOMATIC CURRENTSIZE CURRENTSTORAGE EMPTY NULL OFFSET OFFSETADD OFFSETDIFF OFFSETSUBTRACT

  OFFSETVALUE POINTER POINTERADD PTRADD POINTERDIFF PTRDIFF POINTERSUBTRACT PTRSUBTRACT POINTERVALUE SIZE STORAGE SYSNULL

• String handling built-in functions, which process character-string and bit-string, graphic and WIDECHAR strings. String arguments can be an arithmetic expression to be converted to string either according to data conversion rules or according to the rules given in the function description.

  Some functions do not support WIDECHAR data.

  String handling built-in functions include:

  BIT BOOL COPY GRAPHIC HIGH INDEX LENGTH LOW LOWERCASE

  MPSTR PROCEDURENAME REPEAT SYSVERSION TRANSLATE TRIM UPPERCASE VALID

• Built-in character-handing functions which accept or return WIDECHAR character-type only.
  • WIDECHAR
  • WCHAR
  • WCHARVAL
  • WHIGH
  • WLOW
• Built-in character-handing functions which accept WIDECHAR arguments where character-type arguments apply; when the return value is a character-string the return type is WIDECHAR if any WIDECHAR arguments are passed.

  CENTERLEFT CENTRELEFT CENTERRIGHT CENTRERIGHT CHARACTER CHAR INDEX LEFT LENGTH MAXLENGTH

  RANK REPEAT REVERSE SEARCH SEARCHR SUBSTR TALLY VERIFY VERIFYR

• JSON support built-in functions.

  JSON (Java Script Object Notation) is a human readable text for transmission of data objects consisting of name-value pairs. It is the most common data format used for browser/server communication and is meant to be a replacement for XML. Whitespace is permitted wherever a delimiter is allowed but is otherwise ignored but counts toward the number of bytes read or written. JSON text must be UTF-8 encoded.

  PL/I supports manipulation (reading and writing) of JSON objects via several built-in functions and with the use of some new attributes. JSON objects map on to a subset of PL/I data types - both scalar and aggregates.

  Example of a JSON object:

  { "Last":   "Presley",
       "First": "Elvis",
       "Address" :
         [ "4860 Las Vegas Blvd",
           "Las Vegas",
           "NV 89139"
         ],
       "Title": "The King",
       "Born" : 1935,
       "Alive": true
    }
  

  It maps to:

  dcl 1 King,
          3  Last                       char(30) varying,
          3  First                       char(30) varying,
          3  Address(3)            char(30) varying,
          3  Title                       char(30) varying,
          3  Born                      fixed bin(31),
          3  Alive                      bit;	
  

  JSON built-in function arguments

  All JSON built-in functions have either two or three argument:

  • The first argument is always a locator (a POINTER expression or OFFSET explicitly declared with an AREA reference) pointing to the JSON text buffer.
  • The second argument is always an expression specifying the length of the buffer in bytes.
  • The third argument may be optional for some built-in functions but when present or required, it is always a reference to a variable (scalar or an aggregate). It must be or contain only computational data types and if a structure, it must not contain any elements that are scaled FIXED BINARY or FIXED DECIMAL (p, q) where q < 0 or q > p, or elements that have * names, UNION or GRAPHIC attributes.
  • JSON built-in functions return FIXED BIN(31) value that represents the result which varies by function.

  The JSON built-in functions are:

  JSONGETARRAYEND JSONGETARRAYSTART JSONGETCOLON JSONGETCOMMA JSONGETMEMBER JSONGETOBJECTEND JSONGETOBJECTSTART JSONGETVALUE JSONPUTARRAYEND

  JSONPUTARRAYSTART JSONPUTCOLON JSONPUTCOMMA JSONPUTMEMBER JSONPUTOBJECTEND JSONPUTOBJECTSTART JSONPUTVALUE JSONVALID

This section describes each built-in. The built-ins are presented in alphabetical order by name. Each built-in definition includes a purpose, syntax, and description (the effect of the built-in). Examples (one or more examples of the built-in usage and results) and restrictions (any restrictions in the use of the built-in) may also be included.

Arguments to built-ins are effectively passed by value, that is, no alteration of the arguments is done.