Introduction

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	INT	MOD	RANDOM	SIGN
  CEIL	MAX	MULTIPLE	ROUND	TRUNC
  FLOOR	MIN	POSINT

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

  ALL	DIMENSION	LBOUND	PROD	SUM
  ANY	HBOUND	POLY

• 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	PLIFILL	PLIMOVE	PLIOVER	XMLCHAR
  HEXIMAGE

• 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:

  DATFIELD	ONCODE	ONFILE	ONLOC	ONSUBCODE
  ONCHAR	ONCONDID	ONKEY	ONSOURCE

• 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	DAYSTODATE	SECS	SECSTODAYS	VALIDDATE
  DATETIME	DAYSTOSECS	SECSTODATE	TIME	WEEKDAY
  DAYS	REPATTERN

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

  HUGE

  TINY

• Input/output built-in functions, which determine the current state of a file. These built-in functions include:

  COUNT	FILEDDINT	LINENO	SAMEKEY
  FILEDDWORD	FILEOPEN	PAGENO

• 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	COS	ERFC	LOG2	SQRT
  ASIN	COSD	EXP	SIN	TAN
  ATAN	COSH	LOG	SIND	TAND
  ATAND	ERF	LOG10	SINH	TANH
  ATANH

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

  COLLATE	PACKAGENAME	PLISAXB	RESIGNAL	UNSPEC
  FLUSH	PLIDUMP	PLISAXC	SOURCEFILE
  HEX	PLIRETC	PLISRTx	SOURCELINE
  LPIPARAMCOUNT	PLIRETV	PLITEST	STRING
  OMITTED	PLISAXA	PRESENT	TALLY

• Precision-handling built-in functions, which manipulate variables with specified precisions, and return the value resulting from the operation. These include:

  ADD	DECIMAL	FIXED	MULTIPLY	PRECISION
  BINARY	DIVIDE	FLOAT

• 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

  CONJG

  RANK

• Storage-handling built-in functions, which provide information on the storage requirements and location of variables. These include:

  ADDR	CURRENTSTORAGE	OFFSETADD	POINTER	POINTERVALUE
  ADDRDATA	EMPTY	OFFSETDIFF	POINTERADD/PTRADD	SIZE
  ALLOCATION	NULL	OFFSETSUBTRACT	POINTERDIFF/PTRDIFF	STORAGE
  CURRENTSIZE	OFFSET	OFFSETVALUE	POINTERSUBTRACT/PTRSUBTRACT	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	INDEX	LOWERCASE	REPEAT	TRIM
  COPY	LENGTH	MPSTR	SYSVERSION	UPPERCASE
  GRAPHIC	LOW	PROCEDURENAME	TRANSLATE	VALID
  HIGH

• 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	INDEX	RANK	SEARCH	TALLY
  CENTERRIGHT / CENTRERIGHT	LEFT	REPEAT	SEARCHR	VERIFY
  CHARACTER / CHAR	LENGTH	REVERSE	SUBSTR	VERIFYR
  COPY	MAXLENGTH	RIGHT

• 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	JSONGETOBJECTEND	JSONPUTCOLON	JSONPUTVALUE
  JSONGETARRAYSTART	JSONGETOBJECTSTART	JSONPUTCOMMA	JSONVALID
  JSONGETCOLON	JSONGETVALUE	JSONPUTMEMBER
  JSONGETCOMMA	JSONPUTARRAYEND	JSONPUTOBJECTEND
  JSONGETMEMBER	JSONPUTARRAYSTART	JSONPUTOBJECTSTART

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.