SOUL $functions: Difference between revisions
No edit summary |
|||
(121 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
Some operations are inefficient or impossible to code in a high-level programming language like <var class="product">SOUL</var>. To overcome this difficulty, <var class="product">SOUL</var> provides a variety of $functions. Many of these functions are deprecated in favor of an OO API method. When that is the case, the $function page notes the matching method. | |||
<div id="otherLists"></div> | |||
The mathematical $functions, and those $functions central to a <var class="product">Model 204</var> product (and which require authorization of that product) are listed separately; you can find links to those sets of $functions in the following table: | |||
= | <div class="showVisit"> | ||
< | <table class="wikitable"> | ||
< | <tr class="head"><th>$Function set</th><th>Description</th></tr> | ||
<!-- Note: Rest of this table in synch with list in $Functions section of M204wiki contents --> | |||
< | <tr><td>[[List of mathematical $functions|$xxxmath]]</td><td>Mathematical $functions</td></tr> | ||
<tr><td>[[SirFact $functions|$Fact_xxx]]</td><td>SirFact $functions</td></tr> | |||
<tr><td>[[List of Janus FTP Server $functions|$Ftp_xxx]]</td><td>Janus FTP Server $functions</td></tr> | |||
<tr><td>[[List of Janus Sockets $functions|$Sock_xxx]]</td><td>Janus Sockets $functions</td></tr> | |||
<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>Janus Web Server $functions</td></tr> | |||
<tr><td>[[List of Sir2000 User Language Tools $functions|Sir2000]]</td><td>Sir2000 User Language Tools $functions</td></tr> | |||
<!--<tr><td>[[List of OCM BOCES $functions]]</td><td>To support SIS</td></tr>--> | |||
</table> | |||
</div> | |||
==List of standard $functions== | |||
The following table lists available <var class="product">SOUL</var> $functions, in alphabetical order. The list is not exhaustive (see the [[#otherLists|table of other $function sets]], above). | |||
<p class="note"><b>Note:</b> Some of the $functions listed below are only available with the purchase of a Model 204 add-on product. The individual page containing such a $function's full description has an itemized list of the add-on products that authorize the use of the $function.</p> | |||
<p> | |||
See also: </p> | |||
<ul> | |||
<li>[[#Using_functions|Using functions]], which reviews coding in <var class="product">SOUL</var> with $functions </li> | |||
<li>[[Notation conventions]], which provides a description of the conventions used in syntax on individual $function pages. </li> | |||
</ul> | |||
<div class="showVisit"> | |||
<table class="wikitable"> | |||
<tr class="head"><th>$Function</th><th>Description</th></tr> | |||
<!-- ************************************************************** --> | |||
<!-- Note that FUNSCHECK.WIKI depends on the format of the function name/description rows - *** SO DON'T MUCK WITH IT!!! *** --> | |||
<!-- ************************************************************** --> | |||
<tr><td>[[$Abbrev]]</td><td>Determine if string is abbreviation within list of words</td></tr> | |||
<tr><td>[[$Account]]</td><td>Account under which the user is logged in.</td></tr> | |||
<tr><td>[[$Acct]]</td><td>User ID under which the user is logged in.</td></tr> | |||
<tr><td>[[$Alpha]]</td><td>Whether a string is composed of only the letters A through Z.</td></tr> | |||
<tr><td>[[$AlphNum]]</td><td>Whether a string is composed of only the letters A through Z and digits 0 through 9.</td></tr> | |||
<tr><td>[[$Arr_Find]]</td><td>Find value within array</td></tr> | |||
<tr><td>[[$Arr_Init]]</td><td>Initialize every element of array to specific value</td></tr> | |||
<tr><td>[[$Arr_Max]]</td><td>Find maximum value in array</td></tr> | |||
<tr><td>[[$Arr_Min]]</td><td>Find minimum value in array</td></tr> | |||
<tr><td>[[$ArrSize]]</td><td>Number of elements in a particular dimension of an array.</td></tr> | |||
<tr><td>[[$Ascii]]</td><td>Input string, converted from EBCDIC to ASCII.</td></tr> | |||
<tr><td>[[$A2E]]</td><td>Translate ASCII to EBCDIC</td></tr> | |||
<tr><td>[[$Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr> | |||
<tr><td>[[$Base64_Encode]]</td><td>Convert byte string to base 64</td></tr> | |||
<tr><td>[[$BgPurge]]</td><td>Cancel "long" sdaemon request initiated with $CommBg</td></tr> | |||
<tr><td>[[$BgQuery]]</td><td>List of "long" sdaemon requests initiated via $CommBg</td></tr> | |||
<tr><td>[[$Binary]]</td><td>A number converted into fixed-point binary.</td></tr> | |||
<tr><td>[[$Bind_List]]</td><td>Return list of bound semaphores onto a $list</td></tr> | |||
<tr><td>[[$Bind]]</td><td>Fast, easy synchronization of system wide resource</td></tr> | |||
<tr><td>[[$BitAnd]]</td><td>Bitwise AND of two integers</td></tr> | |||
<tr><td>[[$BitOr]]</td><td>Bitwise OR of two integers</td></tr> | |||
<tr><td>[[$BldProc]]</td><td>Enables a request to build a temporary procedure.</td></tr> | |||
<tr><td>[[$Buffer_Position]]</td><td>Current Universal Buffer position.</td></tr> | |||
<tr><td>[[$Buffer_Size]]</td><td>Size of user's Universal Buffer.</td></tr> | |||
<tr><td>[[$Buffer_Used]]</td><td>Amount of data currently in Universal Buffer</td></tr> | |||
<tr><td>[[$Bump]]</td><td>Bump a user</td></tr> | |||
<tr><td>[[$CenqCt]]</td><td>Number of unused entries within the resource enqueuing table.</td></tr> | |||
<tr><td>[[$Center]]</td><td>Center string</td></tr> | |||
<tr><td>[[$CfStatL]]</td><td>List of statistics for users holding critical file resources</td></tr> | |||
<tr><td>[[$ChkMod]]</td><td>Whether the terminal operator entered data in any full-screen input field.</td></tr> | |||
<tr><td>[[$ChkPat]]</td><td>Syntax of a pattern.</td></tr> | |||
<tr><td>[[$ChkpInf]]</td><td>Information about checkpoints</td></tr> | |||
<tr><td>[[$ChkTag]]</td><td>Whether any erroneous full-screen input has been entered by the end user.</td></tr> | |||
<tr><td>[[$Close]]</td><td>Close file or group in User Language request</td></tr> | |||
<tr><td>[[$Cms]]</td><td>Determine if online is running under CMS</td></tr> | |||
<tr><td>[[$Code]]</td><td>Encoding facility.</td></tr> | |||
<tr><td>[[$Command]]</td><td>Execute Model 204 command on sdaemon, results to image</td></tr> | |||
<tr><td>[[$CommBg]]</td><td>Execute Model 204 commands on sdaemon</td></tr> | |||
<tr><td>[[$CommndL]]</td><td>Execute Model 204 command on sdaemon, results to $list</td></tr> | |||
<tr><td>[[$Context]]</td><td>Determine if string is name of open file or group</td></tr> | |||
<tr><td>[[$Curfile]]</td><td>Name of the file from which the current record has been selected.</td></tr> | |||
<tr><td>[[$Currec]]</td><td>Integer equal to the internal number of the current record.</td></tr> | |||
<tr><td>[[$C2D]]</td><td>Convert binary byte string to integer</td></tr> | |||
<tr><td>[[$C2X]]</td><td>A translation of each byte within a character string to its two-byte hexadecimal representation.</td></tr> | |||
<tr><td>[[$DaemonMasterNumber]]</td><td>Get user number of master thread</td></tr> | |||
<tr><td>[[$DaemonParentNumber]]</td><td>Get user number of parent thread</td></tr> | |||
<tr><td><div id="datex"></div>[[$Date]]</td><td>Current date in yy-mm-dd format.</td></tr> | |||
<tr><td>[[$DateChg]]</td><td>Specified number of days, added to or subtracted from a given date.</td></tr> | |||
<tr><td>[[$DateChk]]</td><td>Whether a given date is valid.</td></tr> | |||
<tr><td>[[$DateCnv]]</td><td>Date converted to a format specified by the user.</td></tr> | |||
<tr><td>[[$DateDif]]</td><td>Difference in days between two dates.</td></tr> | |||
<tr><td>[[$DateJ]]</td><td>Current date in "yy.ddd" format.</td></tr> | |||
<tr><td>[[$DateP]]</td><td>Current date in "dd mon yy" format.</td></tr> | |||
<tr><td>[[$DAY]]</td><td>Day name of the input day-number.</td></tr> | |||
<tr><td>[[$DayI]]</td><td>Number reflecting current day of the week.</td></tr> | |||
<tr><td>[[$Deblank]]</td><td>Substring of a string, with leading and trailing blanks removed.</td></tr> | |||
<tr><td>[[$Decode]]</td><td>Decoding facility.</td></tr> | |||
<tr><td>[[$Deflate]]</td><td>Compress a longstring with Deflate</td></tr> | |||
<tr><td>[[$DelCh]]</td><td>Remove characters from string, compress and strip blanks</td></tr> | |||
<tr><td>[[$Delg_Subsys]]</td><td>Delete subsystem-wide global</td></tr> | |||
<tr><td>[[$Delg_Sys]]</td><td>Delete system-wide global</td></tr> | |||
<tr><td>[[$Delimr]]</td><td>Insert delimiter string into input string at regular positions</td></tr> | |||
<tr><td>[[$Dscr]]</td><td>Decoding facility.</td></tr> | |||
<tr><td>[[$Dsn]]</td><td>Data set name when you specify a file's DD name and the ordinal number.</td></tr> | |||
<tr><td>[[$DsnNum]]</td><td>Total number of data sets defined for a file when you specify the file's DD name.</td></tr> | |||
<tr><td>[[$D2C]]</td><td>Binary byte representation of integer</td></tr> | |||
<tr><td>[[$D2X]]</td><td>Hex representation of integer</td></tr> | |||
<tr><td>[[$Ebcdic]]</td><td>Convert input string from ASCII to EBCDIC</td></tr> | |||
<tr><td>[[$EcbDGet]]</td><td>Get string data associated with an Event Control Block (ECB)</td></tr> | |||
<tr><td>[[$EcbDSet]]</td><td>Set string data associated with an Event Control Block (ECB)</td></tr> | |||
<tr><td>[[$EcbTest]]</td><td>Check an Event Control Block (ECB) to see if it is posted</td></tr> | |||
<tr><td>[[$EcfStat]]</td><td>Returns the detailed completion code from the previous EXTERNAL statement.</td></tr> | |||
<tr><td>[[$Edit]]</td><td>Edited numeric and alphanumeric text</td></tr> | |||
<tr><td>[[$EdScan]]</td><td>Scan list of entities in online</td></tr> | |||
<tr><td>[[$Eformat]]</td><td>Exponent notations from converted numeric values</td></tr> | |||
<tr><td>[[$Encrypt]]</td><td>A one-way encryption of a character string.</td></tr> | |||
<tr><td>[[$Ent_Print]]</td><td>Set automatic character entity substitution</td></tr> | |||
<tr><td>[[$Ent_Tab]]</td><td>retrieve/modify character entity substitution table</td></tr> | |||
<tr><td>[[$Ent]]</td><td>Do character entity substitution</td></tr> | |||
<tr><td>[[$Enter]]</td><td>Efficient terminal dialogue with users of data entry applications.</td></tr> | |||
<tr><td>[[$ErrClr]]</td><td>Clears the error message text returned by the $ErrMsg and $Fsterr functions.</td></tr> | |||
<tr><td>[[$ErrMsg]]</td><td>Prefix and text of the last counting error or request cancellation message received.</td></tr> | |||
<tr><td>[[$ErrSet]]</td><td>Increment or clear number of counting errors, set $ErrMsg</td></tr> | |||
<tr><td>[[$E2A]]</td><td>Translate EBCDIC to ASCII</td></tr> | |||
<tr><td>[[$FakeEnt]]</td><td>Prepare fake ENTER to automatically satisfy next full screen read</td></tr> | |||
<tr><td>[[$FDef]]</td><td>String that describes the attributes of a field in a <var class="product">Model 204</var> file.</td></tr> | |||
<tr><td>[[$Field_Image]]</td><td>Return field values into an image</td></tr> | |||
<tr><td>[[$Field_List]]</td><td>Return field values into a $list</td></tr> | |||
<tr><td>[[$Field_ListI]]</td><td>Return field values into a $list mapped to an image</td></tr> | |||
<tr><td>[[$FieldgroupId]]</td><td>The ID of the current field group. (Available as of Model 204 version 7.5.)</td></tr> | |||
<tr><td>[[$FieldgroupOccurrence]]</td><td>The current occurrence number of the field group. (Available as of Model 204 version 7.5.)</td></tr> | |||
<tr><td>[[$FIniTim]]</td><td>File initialization YYDDDMMHHSSTH</td></tr> | |||
<tr><td>[[$FiStat]]</td><td>Retrieve file's statistics into string</td></tr> | |||
<tr><td>[[$FiStatL]]</td><td>Retrieve set of files' statistics into list</td></tr> | |||
<tr><td>[[$FldLen]]</td><td>Length of a field.</td></tr> | |||
<tr><td>[[$Float]]</td><td>Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).</td></tr> | |||
<tr><td>[[$FloatD]]</td><td>Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string). </td></tr> | |||
<tr><td>[[$FlsAcc]]</td><td>User's access rights to a particular field.</td></tr> | |||
<tr><td>[[$FlsChk]]</td><td>Whether a given set of field level security accesses is valid for a field.</td></tr> | |||
<tr><td>[[$FreeOpt]]</td><td>Free optional file or group from subsystem</td></tr> | |||
<tr><td>[[$Fsterr]]</td><td>Variable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero.</td></tr> | |||
<tr><td>[[$FunForc]]</td><td>Cancel running or waiting Fast/Unload request</td></tr> | |||
<tr><td>[[$FunImg]]</td><td>Retrieve data from active Fast/Unload request into image</td></tr> | |||
<tr><td>[[$FunList]]</td><td>$list of active and enqueued Fast/Unload requests</td></tr> | |||
<tr><td>[[$FunLoad]]</td><td>Fast/Unload records in Model 204 list or found set</td></tr> | |||
<tr><td>[[$FunPurg]]</td><td>Purge running or waiting Fast/Unload request</td></tr> | |||
<tr><td>[[$FunSkip]]</td><td>Skip to next output record for $FunImg, $FunsStr</td></tr> | |||
<tr><td>[[$FunsStr]]</td><td>Retrieve data from active Fast/Unload request into string</td></tr> | |||
<tr><td>[[$FunWait]]</td><td>Wait until asynchronous Fast/Unload request completes</td></tr> | |||
<tr><td>[[$Getg]]</td><td>Information stored by a $SETG function.</td></tr> | |||
<tr><td>[[$GetL]]</td><td>Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command.</td></tr> | |||
<tr><td>[[$GetP]]</td><td>Page number currently on the user's terminal or on the output data set specified by a USE command.</td></tr> | |||
<tr><td>[[$GrmLoc]]</td><td>Location of a missing member.</td></tr> | |||
<tr><td>[[$GrmName]]</td><td>File name of a missing member.</td></tr> | |||
<tr><td>[[$GrnLeft]]</td><td>Number of optional files that may fail before MAXFAIL is exceeded.</td></tr> | |||
<tr><td>[[$GrnMiss]]</td><td>Number of missing members.</td></tr> | |||
<tr><td>[[$GunZip]]</td><td>Decompress a longstring with GUNZIP</td></tr> | |||
<tr><td>[[$GZip]]</td><td>Compress a longstring with GZip</td></tr> | |||
<tr><td>[[$HexA]]</td><td>Convert hexadecimal string to EBCDIC equivalent</td></tr> | |||
<tr><td>[[$HPage]]</td><td>String of special characters whose length is equal to the value specified as the $HPage argument.</td></tr> | |||
<tr><td>[[$Hsh]]</td><td>A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.</td></tr> | |||
<tr><td>[[$IHexA]]</td><td>Convert EBCDIC string to hexadecimal equivalent</td></tr> | |||
<tr><td>[[$ImgInf]]</td><td>Retrieve image item by variable name</td></tr> | |||
<tr><td>[[$ImgOvl]]</td><td>Replace image item value</td></tr> | |||
<tr><td>[[$Incrg]]</td><td>Performs simple arithmetic on global variables.</td></tr> | |||
<tr><td>[[$IncStat]]</td><td>Increment local system statistic</td></tr> | |||
<tr><td>[[$Index]]</td><td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN.</td></tr> | |||
<tr><td>[[$Inflate]]</td><td>Decompress a longstring with inflate</td></tr> | |||
<tr><td>[[$ItsOpen]]</td><td>Whether or not a file is open.</td></tr> | |||
<tr><td>[[$ItsRemote]]</td><td>Whether the current file or group is remote or scattered.</td></tr> | |||
<tr><td>[[$JobAuth]]</td><td>Determine if user has authorization for USE $JOB</td></tr> | |||
<tr><td>[[$Jobcode]]</td><td>Allows a request that is part of one step of a <var class="product">Model 204</var> batch run to communicate with a subsequent step.</td></tr> | |||
<tr><td>[[$JpStat]]</td><td>Retrieve Janus port's statistics into string</td></tr> | |||
<tr><td>[[$JpStatL]]</td><td>Retrieve statistics for set of Janus pors into $list</td></tr> | |||
<tr><td>[[$LangSpc]]</td><td>String containing the binary value of a character in a specified language.</td></tr> | |||
<tr><td>[[$LangSrt]]</td><td>A binary string translated to sort according to the NLSORT macro for the specified language.</td></tr> | |||
<tr><td>[[$LangUst]]</td><td>Previously $LangSrt'ed string translated back to its original form.</td></tr> | |||
<tr><td>[[$Len]]</td><td>Length of a value in a field.</td></tr> | |||
<tr><td>[[$List_Add_Ordered]]</td><td>Add an item to an ordered $list</td></tr> | |||
<tr><td>[[$List_Add_Unique_Ordered]]</td><td>Conditionally add an item to an ordered $list</td></tr> | |||
<tr><td>[[$List_Add_Unique]]</td><td>Conditionally add an item to a $list</td></tr> | |||
<tr><td>[[$List_Capture]]</td><td>Capture print data to $list</td></tr> | |||
<tr><td>[[$List_Conv_Item]]</td><td>Convert $list to single delimited $list item</td></tr> | |||
<tr><td>[[$List_Copy_Items]]</td><td>Copy items between $lists</td></tr> | |||
<tr><td>[[$List_Diff_Item]]</td><td>Differences between $list and delimited $list item</td></tr> | |||
<tr><td>[[$List_Global and $List_Session]]</td><td>Access/create global/session $list</td></tr> | |||
<tr><td>[[$List_Global_Del and $List_Session_Del]]</td><td>Delete global/session $lists</td></tr> | |||
<tr><td>[[$List_Global_List and $List_Session_List]]</td><td>List global/session $lists</td></tr> | |||
<tr><td>[[$List_MaxIL]]</td><td>Return maximum $list item length</td></tr> | |||
<tr><td>[[$List_Print]]</td><td>Display contents of a $list</td></tr> | |||
<tr><td>[[$ListAdd_Lstr]]</td><td>Add longstring as new $list item</td></tr> | |||
<tr><td>[[$ListAdd]]</td><td>Add string as new $list item</td></tr> | |||
<tr><td>[[$ListAddI]]</td><td>Add image as new $list item</td></tr> | |||
<tr><td>[[$ListAdj]]</td><td>Adjust length of $list item</td></tr> | |||
<tr><td>[[$ListChk]]</td><td>Validate a $list identifier</td></tr> | |||
<tr><td>[[$ListCmp]]</td><td>Compare two $lists and produce $list describing differences</td></tr> | |||
<tr><td>[[$ListCnt]]</td><td>Number of items in $list</td></tr> | |||
<tr><td>[[$ListCpy]]</td><td>Copy $list</td></tr> | |||
<tr><td>[[$ListDel]]</td><td>Release CCATEMP storage used for $list</td></tr> | |||
<tr><td>[[$ListFind]]</td><td>Find string in $list</td></tr> | |||
<tr><td>[[$ListFindI and $ListFindI_Up]]</td><td>Find image item in $list</td></tr> | |||
<tr><td>[[$ListFindI_Sub]]</td><td>Build $list subset based on image item</td></tr> | |||
<tr><td>[[$ListILn]]</td><td>Length of $list item</td></tr> | |||
<tr><td>[[$Listimg_Copy]]</td><td>Copy a $list's image association</td></tr> | |||
<tr><td>[[$ListImg]]</td><td>Associate an image with a $list</td></tr> | |||
<tr><td>[[$ListInf_Lstr]]</td><td>Retrieve $list item into longstring</td></tr> | |||
<tr><td>[[$ListInf]]</td><td>Retrieve $list item into string</td></tr> | |||
<tr><td>[[$ListInfI]]</td><td>Retrieve $list item into image</td></tr> | |||
<tr><td>[[$ListIns_Lstr]]</td><td>Insert string into a $list</td></tr> | |||
<tr><td>[[$ListIns]]</td><td>Insert string into a $list</td></tr> | |||
<tr><td>[[$ListInsI]]</td><td>Insert image into a $list</td></tr> | |||
<tr><td>[[$ListLoc]]</td><td>Locate string in $list</td></tr> | |||
<tr><td>[[$ListLup]]</td><td>Locate string in $list, searching backwards</td></tr> | |||
<tr><td>[[$ListMove]]</td><td>Move a $list</td></tr> | |||
<tr><td>[[$ListNew]]</td><td>Create empty $list</td></tr> | |||
<tr><td>[[$ListNewA]]</td><td>Create array of empty $lists</td></tr> | |||
<tr><td>[[$ListNewAI]]</td><td>Create array of empty $lists associated with image</td></tr> | |||
<tr><td>[[$ListNewI]]</td><td>Create empty $list associated with image</td></tr> | |||
<tr><td>[[$ListOvl]]</td><td>Overlay part of $list item with string</td></tr> | |||
<tr><td>[[$ListOvlI]]</td><td>Overlay part of $list item with image item</td></tr> | |||
<tr><td>[[$ListRem]]</td><td>Remove item from $list</td></tr> | |||
<tr><td>[[$ListRep_Lstr]]</td><td>Replace a $list item with a longstring</td></tr> | |||
<tr><td>[[$ListRep]]</td><td>Replace a $list item with a string</td></tr> | |||
<tr><td>[[$ListRepI]]</td><td>Replace $list item with an image</td></tr> | |||
<tr><td>[[$ListRst]]</td><td>Restore global $list</td></tr> | |||
<tr><td>[[$ListSav and $ListSave]]</td><td>Save global $list</td></tr> | |||
<tr><td>[[$ListSavL]]</td><td>Count and names of available global $lists</td></tr> | |||
<tr><td>[[$ListSort and $ListSrt]]</td><td>Sort $list</td></tr> | |||
<tr><td>[[$ListSub]]</td><td>Create $list that is subset of input $list</td></tr> | |||
<tr><td>[[$ListUpd]]</td><td>Produce $list from input $list using $list of updates</td></tr> | |||
<tr><td>[[$Lowcase]]</td><td>A lower case string translated from an uppercase or mixed case string</td></tr> | |||
<tr><td>[[$LstFld]]</td><td>Field names in a file, along with their field descriptions, into an image.</td></tr> | |||
<tr><td>[[$LstProc]]</td><td>Information that is stored for a procedure.</td></tr> | |||
<tr><td>[[$Lstr_Add_UserBuffer]]</td><td>Add longstring to user buffer</td></tr> | |||
<tr><td>[[$Lstr_Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr> | |||
<tr><td>[[$Lstr_Base64_Encode]]</td><td>Convert byte string to base 64</td></tr> | |||
<tr><td>[[$Lstr_C2X]]</td><td>Convert byte string to hexadecimal</td></tr> | |||
<tr><td>[[$Lstr_Get_Image and $Lstr_Set_Image]]</td><td>Longstring to/from image</td></tr> | |||
<tr><td>[[$Lstr_Get_Userbuffer]]</td><td>Get user buffer contents to a longstring</td></tr> | |||
<tr><td>[[$Lstr_Global and $Lstr_Session]]</td><td>Bind to global/session longstring</td></tr> | |||
<tr><td>[[$Lstr_Global_Del and $Lstr_Session_Del]]</td><td>Delete global or session longstring</td></tr> | |||
<tr><td>[[$Lstr_Global_Get and $Lstr_Session_Get]]</td><td>Get global or session longstring</td></tr> | |||
<tr><td>[[$Lstr_Global_Set and $Lstr_Session_Set]]</td><td>Set global or session longstring</td></tr> | |||
<tr><td>[[$Lstr_Index]]</td><td>Find a string inside a longstring</td></tr> | |||
<tr><td>[[$Lstr_Left]]</td><td>Leftmost characters of a longstring</td></tr> | |||
<tr><td>[[$Lstr_Len]]</td><td>Length of a longstring</td></tr> | |||
<tr><td>[[$Lstr_Parse]]</td><td>Part of longstring preceding character in delimiter set</td></tr> | |||
<tr><td>[[$Lstr_ParseX]]</td><td>Part of longstring following character in delimiter set</td></tr> | |||
<tr><td>[[$Lstr_Right]]</td><td>Rightmost characters of a longstring</td></tr> | |||
<tr><td>[[$Lstr_Set_UserBuffer]]</td><td>Set user buffer to longstring value</td></tr> | |||
<tr><td>[[$Lstr_Substr]]</td><td>Substring of a longstring</td></tr> | |||
<tr><td>[[$Lstr_SubWord]]</td><td>Substring of a longstring using word counts</td></tr> | |||
<tr><td>[[$Lstr_Translate]]</td><td>Translate longstring</td></tr> | |||
<tr><td>[[$Lstr_Unblank]]</td><td>Remove extraneous blanks from longstring</td></tr> | |||
<tr><td>[[$Lstr_Windex]]</td><td>Return the position of a word within a long string</td></tr> | |||
<tr><td>[[$Lstr_Word]]</td><td>Return a word from a long string</td></tr> | |||
<tr><td>[[$Lstr_Words]]</td><td>Return the number of words in a long string</td></tr> | |||
<tr><td>[[$Lstr_X2C]]</td><td>Convert from hexadecimal to byte string</td></tr> | |||
<tr><td>[[$Lstr]]</td><td>Treat a string as longstring</td></tr> | |||
<tr><td>[[$MisGrup]]</td><td>Group name if the error occurred in group context, null if in file context.</td></tr> | |||
<tr><td>[[$MisLoc]]</td><td>Location of a missing member or file.</td></tr> | |||
<tr><td>[[$MisName]]</td><td>File name of a missing member or file.</td></tr> | |||
<tr><td>[[$MisNum]]</td><td>Number of files that failed in a group.</td></tr> | |||
<tr><td>[[$MisStmt]]</td><td>Statement that caused the ON unit to be entered.</td></tr> | |||
<tr><td>[[$Mod]]</td><td>Remainder that results when one argument is divided by the another argument.</td></tr> | |||
<tr><td>[[$Occurs]]</td><td>Whether a field has the OCCURS attribute.</td></tr> | |||
<tr><td>[[$Oneof]]</td><td>Table lookup that can replace a series of IF conditions.</td></tr> | |||
<tr><td>[[$Pack]]</td><td>Packed decimal representation of a string.</td></tr> | |||
<tr><td>[[$Pad]]</td><td>Designated character padded to the left.</td></tr> | |||
<tr><td>[[$PadR]]</td><td>Designated character padded to the right</td></tr> | |||
<tr><td>[[$Parse]]</td><td>Part of string preceding character in delimiter set</td></tr> | |||
<tr><td>[[$ParseX]]</td><td>Part of string following character in delimiter set</td></tr> | |||
<tr><td>[[$Post]]</td><td>Indicates that an event has occurred; the thread waiting on an ECB can resume processing.</td></tr> | |||
<tr><td>[[$PrcLEx]]</td><td>$list of information about procedures in file</td></tr> | |||
<tr><td>[[$PrcLExG]]</td><td>$list of information about procedures in group or file</td></tr> | |||
<tr><td>[[$Priorty]]</td><td>Change a user's priority</td></tr> | |||
<tr><td>[[$Proc_List]]</td><td>$list of information about procedures in file</td></tr> | |||
<tr><td>[[$Proc_ListG]]</td><td>$list of information about procedures in group or file</td></tr> | |||
<tr><td>[[$Proc_Touch]]</td><td>Change a procedure's last-update date and user</td></tr> | |||
<tr><td>[[$ProcCls]]</td><td>Close procedure before reaching end</td></tr> | |||
<tr><td>[[$ProcDat]]</td><td>Add lines from procedure to $list</td></tr> | |||
<tr><td>[[$ProcGet]]</td><td>Next line of procedure</td></tr> | |||
<tr><td>[[$ProcLoc]]</td><td>Locate any of set of strings in procedure</td></tr> | |||
<tr><td>[[$ProcOpn]]</td><td>Open procedure for $ProcDat, $ProcGet, $ProcLoc</td></tr> | |||
<tr><td>[[$Random_Seed]]</td><td>Build seed specifying series of $Random results</td></tr> | |||
<tr><td>[[$Random]]</td><td>Get next random number</td></tr> | |||
<tr><td>[[$RdProc]]</td><td>Lines of a User Language procedure, retrieved in sequential order, that is stored in a <var class="product">Model 204</var> file.</td></tr> | |||
<tr><td>[[$Read]]</td><td>An echo of the data a user enters as a request is evaluated</td></tr> | |||
<tr><td>[[$ReadInv]]</td><td>Performs the same function as $READ, except that input from the terminal is not echoed.</td></tr> | |||
<tr><td>[[$ReadLc]]</td><td>An echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting.</td></tr> | |||
<tr><td>[[$RegexMatch]]</td><td>Whether string matches regex</td></tr> | |||
<tr><td>[[$RegexReplace]]</td><td>Replace matching strings</td></tr> | |||
<tr><td>[[$Remote]]</td><td>VTAMNAME value of the originating <var class="product">Model 204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model 204</var> regions.</td></tr> | |||
<tr><td>[[$ResetN]]</td><td>Reset or view M204 parameter</td></tr> | |||
<tr><td>[[$Reverse]]</td><td>Reversed order of a string.</td></tr> | |||
<tr><td>[[$RlcFile]]</td><td>Name of the file in which the last record locking conflict occurred.</td></tr> | |||
<tr><td>[[$RlcRec]]</td><td>Internal record number for which the last record locking conflict occurred.</td></tr> | |||
<tr><td>[[$RlcUid]]</td><td>ID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node.</td></tr> | |||
<tr><td>[[$RlcUsr]]</td><td>User number of the user with which the request conflicted when the last record locking conflict occurred.</td></tr> | |||
<tr><td>[[$Round]]</td><td>Number, rounded to a specified number of decimal places.</td></tr> | |||
<tr><td>[[$Scan]]</td><td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX.</td></tr> | |||
<tr><td>[[$Sclass]]</td><td>Current user's subsystem user class.</td></tr> | |||
<tr><td>[[$Screen_attr]]</td><td>Get screen item attributes as a blank-delimited string</td></tr> | |||
<tr><td>[[$Screen_clear]]</td><td>Clear tagged and/or modified attributes in a screen</td></tr> | |||
<tr><td>[[$Screen_mod]]</td><td>Set modified attribute for a screen item</td></tr> | |||
<tr><td>[[$ScrHide]]</td><td>Hide lines in SCREEN</td></tr> | |||
<tr><td>[[$ScrSize]]</td><td>Change size of field on SCREEN</td></tr> | |||
<tr><td>[[$ScrWide]]</td><td>Allow SCREEN to accept fields wider than 79</td></tr> | |||
<tr><td>[[$Session_$Session_Id_$Session_Owner_and_$Session_Timeout|$Session, $Session_Id, $Session_Owner, <br>and $Session_Timeout]]</td><td>Return values for currently open session</td></tr> | |||
<tr><td>[[$Session_Close]]</td><td>Close an open session</td></tr> | |||
<tr><td>[[$Session_Create]]</td><td>Create a new session</td></tr> | |||
<tr><td>[[$Session_Delete]]</td><td>Delete a session</td></tr> | |||
<tr><td>[[$Session_List]]</td><td>Get list of sessions</td></tr> | |||
<tr><td>[[$Session_Open]]</td><td>Open a session</td></tr> | |||
<tr><td>[[$Setg_Subsys_List]]</td><td>Get list of subsystem-wide globals</td></tr> | |||
<tr><td>[[$Setg_Subsys]]</td><td>Set subsystem-wide global</td></tr> | |||
<tr><td>[[$Setg_Sys_List]]</td><td>Get list of system-wide globals</td></tr> | |||
<tr><td>[[$Setg_Sys]]</td><td>Set system-wide global</td></tr> | |||
<tr><td>[[$Setg]]</td><td>A created or changed entry in the global variable section of GTBL.</td></tr> | |||
<tr><td>[[$SetL]]</td><td>Sets the current line counter for the output device currently in effect.</td></tr> | |||
<tr><td>[[$SetP]]</td><td>Sets the current page number for the output device currently in effect.</td></tr> | |||
<tr><td>[[$SetStat]]</td><td>Set local system statistic</td></tr> | |||
<tr><td><div id="datetime"></div>[[$Sir_Date]]</td><td>Get current datetime</td></tr> | |||
<tr><td>[[$Sir_DateFmt]]</td><td>Validate datetime format</td></tr> | |||
<tr><td><div id="daten"></div>[[$Sir_DateN]]</td><td>Current date and time as number of seconds/300</td></tr> | |||
<tr><td>[[$Sir_DateND]]</td><td>Current date as number of days</td></tr> | |||
<tr><td>[[$Sir_DateNM]]</td><td>Current date and time as number of milliseconds</td></tr> | |||
<tr><td>[[$Sir_DateNS]]</td><td>Current date and time as number of seconds</td></tr> | |||
<tr><td>[[$Sir_Date2N]]</td><td>Convert datetime string to number of seconds/300</td></tr> | |||
<tr><td>[[$Sir_Date2ND]]</td><td>Convert datetime string to number of days</td></tr> | |||
<tr><td>[[$Sir_Date2NM]]</td><td>Convert datetime string to number of milliseconds</td></tr> | |||
<tr><td>[[$Sir_Date2NS]]</td><td>Convert datetime string to number of seconds</td></tr> | |||
<tr><td>[[$Sir_Login]]</td><td>Perform secured web or sockets login</td></tr> | |||
<tr><td>[[$Sir_ND2Date]]</td><td>Convert datetime number of days to string</td></tr> | |||
<tr><td>[[$Sir_NM2Date]]</td><td>Convert datetime number of milliseconds to string</td></tr> | |||
<tr><td>[[$Sir_NS2Date]]</td><td>Convert datetime number of seconds to string</td></tr> | |||
<tr><td>[[$Sir_N2Date]]</td><td>Convert datetime number of seconds/300 to string</td></tr> | |||
<tr><td>[[$Sir_Wild]]</td><td>Test string against a wildcard string</td></tr> | |||
<tr><td>[[$SirJGet]]</td><td>Place audit trail data on $list</td></tr> | |||
<tr><td>[[$SirMsg]]</td><td>Line of current $SirMsgP procedure</td></tr> | |||
<tr><td>[[$SirMsgP]]</td><td>Load procedure for retrieval via $SirMsg</td></tr> | |||
<tr><td>[[$SirParm]]</td><td>Set user-specific value, controlling Sirius products</td></tr> | |||
<tr><td>[[$SirProd]]</td><td>Determine availability of Sirius product or capability</td></tr> | |||
<tr><td>[[$SirSite]]</td><td>Current Sirius customer site ID</td></tr> | |||
<tr><td>[[$SirTime]]</td><td>Current time as YYDDDHHMISSXX</td></tr> | |||
<tr><td>[[$SirVer]]</td><td>Current version number of Sirius product</td></tr> | |||
<tr><td>[[$SirWarn]]</td><td>Send warning or message to user(s)</td></tr> | |||
<tr><td>[[$Slstats]]</td><td>Resets the recording of since-last statistics anywhere within a request.</td></tr> | |||
<tr><td>[[$SndMail]]</td><td>Send an email message</td></tr> | |||
<tr><td>[[$Sndx]]</td><td>SOUNDEX code of an argument.</td></tr> | |||
<tr><td>[[$Square]]</td><td>A number multiplied by itself.</td></tr> | |||
<tr><td>[[$SsStat]]</td><td>Retrieve subsystem's statistics into string</td></tr> | |||
<tr><td>[[$SsStatL]]</td><td>Retrieve statistics for set of subsystems into $list</td></tr> | |||
<tr><td>[[$Stat]]</td><td>Current value of any user statistic.</td></tr> | |||
<tr><td>[[$StatD]]</td><td>Calculate differences and rates for statistics strings</td></tr> | |||
<tr><td>[[$StatLD]]</td><td>Calculate differences and rates for statistics $lists</td></tr> | |||
<tr><td>[[$Status]]</td><td>The success or failure of the last executed external I/O or program communication statement.</td></tr> | |||
<tr><td>[[$StatusD]]</td><td>More detailed description of a condition returned by $STATUS.</td></tr> | |||
<tr><td>[[$Str]]</td><td>Treat a longstring as string</td></tr> | |||
<tr><td>[[$StrAnd]]</td><td>Bit-wise AND two strings</td></tr> | |||
<tr><td>[[$Strip]]</td><td>A number with suppressed leading zeros.</td></tr> | |||
<tr><td>[[$StrOr]]</td><td>Bit-wise OR two strings</td></tr> | |||
<tr><td>[[$StrXor]]</td><td>Bit-wise exclusive OR two strings</td></tr> | |||
<tr><td>[[$SubCnt]]</td><td>Count occurrences of one string in another</td></tr> | |||
<tr><td>[[$SubErs]]</td><td>Remove occurrence of one string from another</td></tr> | |||
<tr><td>[[$SubIns]]</td><td>Insert string inside another string</td></tr> | |||
<tr><td>[[$SubRep]]</td><td>Replace occurrences of string</td></tr> | |||
<tr><td>[[$Substr]]</td><td>Substring of a string.</td></tr> | |||
<tr><td>[[$Subsys]]</td><td>Status of an APSY subsystem.</td></tr> | |||
<tr><td>[[$SyStat]]</td><td>Retrieve system statistics into string</td></tr> | |||
<tr><td>[[$TableC]]</td><td>Information provided by TABLEC command</td></tr> | |||
<tr><td>[[$TermId]]</td><td>Terminal ID of current user thread</td></tr> | |||
<tr><td>[[$Time]]</td><td>Current time in hh:mm:ss format.</td></tr> | |||
<tr><td>[[$TkStat]]</td><td>Retrieve task's statistics into string</td></tr> | |||
<tr><td>[[$TkStatL]]</td><td>Retrieve statistics for all tasks into $list</td></tr> | |||
<tr><td>[[$TsoAtt]]</td><td>Attach program in user's TSO address space</td></tr> | |||
<tr><td>[[$TsoCall]]</td><td>Call program in user's TSO address space</td></tr> | |||
<tr><td>[[$TsoCan]]</td><td>Cancel program invoked via $TsoAtt</td></tr> | |||
<tr><td>[[$TsoCmd]]</td><td>Invoke command in user's TSO address space</td></tr> | |||
<tr><td>[[$TsoExec]]</td><td>Invoke CLIST in user's TSO address space</td></tr> | |||
<tr><td>[[$TsoExit]]</td><td>Terminate TSO full screen interface session, stack command</td></tr> | |||
<tr><td>[[$TSOId]]</td><td>TSO userid user's thread</td></tr> | |||
<tr><td>[[$TSOStat]]</td><td>Status of program invoked via $TsoAtt</td></tr> | |||
<tr><td>[[$TSOWait]]</td><td>Wait for program invoked via $TsoAtt to complete</td></tr> | |||
<tr><td>[[$Unbin]]</td><td>Value converted from binary to string representation.</td></tr> | |||
<tr><td>[[$Unbind_and_$UnbindW]]</td><td>$Unbind and $UnbindW: Unbind resource previously bound via $Bind</td></tr> | |||
<tr><td>[[$Unblank]]</td><td>Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.</td></tr> | |||
<tr><td>[[$Unfloat]]</td><td>Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.</td></tr> | |||
<tr><td>[[$Unpack]]</td><td>Unpacked decimal data </td></tr> | |||
<tr><td>[[$UnPost]]</td><td>Resets a specified Event Control Block (ECB) to an unposted state.</td></tr> | |||
<tr><td>[[$UnqRec]]</td><td><p>In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pair</p><p>If no uniqueness violation occurred. returns -1.</p></td></tr> | |||
<tr><td>[[$UnSpace]]</td><td>Normalize spaces and quotes</td></tr> | |||
<tr><td>[[$Upcase]]</td><td>An uppercase string converted from a lower or mixed case string.</td></tr> | |||
<tr><td>[[$Update]]</td><td>Name of the group update file or the current file.</td></tr> | |||
<tr><td>[[$UpdFile]]</td><td>Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.</td></tr> | |||
<tr><td>[[$UpdFld]]</td><td>Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.</td></tr> | |||
<tr><td>[[$UpdLoc]]</td><td>Location name (node name) of the current update unit (Parallel Query Option/204 only).</td></tr> | |||
<tr><td>[[$UpdOval]]</td><td>Value of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict. </td></tr> | |||
<tr><td>[[$UpdRec]]</td><td>File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.</td></tr> | |||
<tr><td>[[$UpdStat]]</td><td>Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.</td></tr> | |||
<tr><td>[[$UpdStmt]]</td><td>Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.</td></tr> | |||
<tr><td>[[$UpdVal]]</td><td>Field value causing a field level constraint violation, or a blank if no violation occurred.</td></tr> | |||
<tr><td>[[$UseASA]]</td><td>Prevent carriage control in USE output</td></tr> | |||
<tr><td>[[$User]]</td><td>User's user number.</td></tr> | |||
<tr><td>[[$Userid]]</td><td>User ID under which the user is logged in.</td></tr> | |||
<tr><td>[[$UsrPriv]]</td><td>Whether a user ID has been granted specific <var class="product">Model 204</var> privileges.</td></tr> | |||
<tr><td>[[$UsStat]]</td><td>Retrieve user's statistics into string</td></tr> | |||
<tr><td>[[$UsStatL]]</td><td>Retrieve statistics for set of users into $list</td></tr> | |||
<tr><td>[[$Verify]]</td><td>Whether every character in one string is present in a second string.</td></tr> | |||
<tr><td>[[$View]]</td><td>Value of a parameter.</td></tr> | |||
<tr><td>[[$Vnum]]</td><td>Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.</td></tr> | |||
<tr><td>[[$Wait]]</td><td>Suspend a user until an Event Control Block (ECB) is posted.</td></tr> | |||
<tr><td>[[$WakeUp]]</td><td>Pause user until specified time</td></tr> | |||
<!--bypass FUNCHECK.WIKI--> | |||
<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>List of Janus Web Server $functions</td></tr> | |||
<tr><td>[[$Windex]]</td><td>Word number of first occurrence of word in phrase</td></tr> | |||
<tr><td>[[$Word]]</td><td>P word in a specified string, delimited by a blank or optionally specified character.</td></tr> | |||
<tr><td>[[$Words]]</td><td>Number of words in a specified string, delimited by a blank or optionally specified character.</td></tr> | |||
<tr><td>[[$X2C]]</td><td>One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.</td></tr> | |||
<tr><td>[[$X2D]]</td><td>Convert hex string to integer</td></tr> | |||
</table> | |||
</div> | |||
==Using functions== | |||
You can use functions in several ways, including, as a term in: | |||
<ul> | <ul> | ||
<li>An expression in a variable assignment statement, for example:</li> | <li>An expression in a variable assignment statement, for example:</li> | ||
Line 22: | Line 428: | ||
<li>The specifications in a PRINT statement</li> | <li>The specifications in a PRINT statement</li> | ||
</ul> | </ul> | ||
<p>A PRINT statement can include a function call anywhere a field name can be used. For example:</p> | <p> | ||
A PRINT statement can include a function call anywhere a field name can be used. For example:</p> | |||
<p class="code">PRINT $EDIT(2573,'99999') | <p class="code">PRINT $EDIT(2573,'99999') | ||
</p> | </p> | ||
Line 35: | Line 442: | ||
<p class="code">%L=$LEN($EDIT(2573,'99999')) | <p class="code">%L=$LEN($EDIT(2573,'99999')) | ||
</p> | </p> | ||
<p>The direct use of function calls in some statements, such as FIND, results in compilation errors. </p> | <p> | ||
The direct use of function calls in some statements, such as FIND, results in compilation errors. </p> | |||
<p>If your request is coded as follows:</p> | |||
====Comparing successful and unsuccessful $function code==== | |||
<p> | |||
If your request is coded as follows:</p> | |||
<p class="code">BEGIN | <p class="code">BEGIN | ||
$EDIT(2573,'99999') | $EDIT(2573,'99999') | ||
END | END | ||
</p> | </p> | ||
<p>The following error is your result:</p> | <p> | ||
The following error is your result:</p> | |||
<p class="code"><b></b>*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999') | <p class="code"><b></b>*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999') | ||
</p> | </p> | ||
<p>However, if you code your request as follows, it works properly:</p> | <p> | ||
However, if you code your request as follows, it works properly:</p> | |||
<p class="code">BEGIN | <p class="code">BEGIN | ||
PRINT $EDIT(2573,'99999') | PRINT $EDIT(2573,'99999') | ||
Line 52: | Line 464: | ||
END | END | ||
</p> | </p> | ||
<p>Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:</p> | ===Function return values=== | ||
<p class="code">% | <p> | ||
Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:</p> | |||
<p class="code">%a = $account | |||
</p> | </p> | ||
<p>This function causes the length of the current value of the FULLNAME field to be compared to 10:</p> | <p> | ||
This function causes the length of the current value of the FULLNAME field to be compared to 10:</p> | |||
<p class="code">IF $LEN(FULLNAME) GT 10 THEN | <p class="code">IF $LEN(FULLNAME) GT 10 THEN | ||
. | . | ||
. | . | ||
. | . | ||
</p> | </p> | ||
<p>Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:</p> | ===Function arguments=== | ||
<p> | |||
Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:</p> | |||
<p class="code">IF $READ('CONTINUE?') EQ 'YES' THEN | <p class="code">IF $READ('CONTINUE?') EQ 'YES' THEN | ||
. | . | ||
. | . | ||
. | . | ||
%X = $ | %X = $mod(COUNT IN CT, %BASE) | ||
</p> | </p> | ||
<p>Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using | ====Rules for function arguments==== | ||
<p> | |||
<p><var class="product">Model 204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:</p> | Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using variables and values in computation#Expressions|Expressions]] for detailed information on expression syntax.</p> | ||
====Argument evaluation and conversion==== | |||
<p> | |||
<var class="product">Model 204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:</p> | |||
<ul> | <ul> | ||
<li>If an argument is expected to be numeric but is a string, <var class="product">Model 204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using | <li>If an argument is expected to be numeric but is a string, <var class="product">Model 204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using variables and values in computation#Relationship between %variable assignment and declaration|Relationship between %variable assignment and declaration]] and [[Using variables and values in computation#Conversion|Conversion]]. </li> | ||
</li> | </li> | ||
<li>If an argument is expected to be a string but is numeric, <var class="product">Model 204</var> converts the number to a string. </li> | <li>If an argument is expected to be a string but is numeric, <var class="product">Model 204</var> converts the number to a string. </li> | ||
Line 82: | Line 503: | ||
</li> | </li> | ||
</ul> | </ul> | ||
== | |||
< | ==User-written functions== | ||
<p> | |||
In addition to the functions provided by <var class="product">SOUL</var>, some customer sites write their own functions based on their particular needs. | |||
Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production. </p> | |||
<blockquote class="note"> | |||
<b>Notes:</b> | |||
< | |||
<b> | |||
<ul> | <ul> | ||
<li> | <li>It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified. | ||
<li>The RESULT macro does not work in Model 204 Version 5.1 and later. Change any use of the RESULT macro in $functions to use the standard LEAVENUM, LEAVEF0 and LEAVESTR macros. | |||
<li>In addition to the above considerations, see the [[Model 204 installation#FUNU|installation instructions relating to FUNU]]. | |||
</ul></blockquote> | |||
< | |||
< | |||
</ul> | |||
<p>Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.</p> | |||
[[Category:SOUL]] | [[Category:SOUL]] |
Latest revision as of 22:57, 25 October 2020
Some operations are inefficient or impossible to code in a high-level programming language like SOUL. To overcome this difficulty, SOUL provides a variety of $functions. Many of these functions are deprecated in favor of an OO API method. When that is the case, the $function page notes the matching method.
The mathematical $functions, and those $functions central to a Model 204 product (and which require authorization of that product) are listed separately; you can find links to those sets of $functions in the following table:
$Function set | Description |
---|---|
$xxxmath | Mathematical $functions |
$Fact_xxx | SirFact $functions |
$Ftp_xxx | Janus FTP Server $functions |
$Sock_xxx | Janus Sockets $functions |
$Web_xxx | Janus Web Server $functions |
Sir2000 | Sir2000 User Language Tools $functions |
List of standard $functions
The following table lists available SOUL $functions, in alphabetical order. The list is not exhaustive (see the table of other $function sets, above).
Note: Some of the $functions listed below are only available with the purchase of a Model 204 add-on product. The individual page containing such a $function's full description has an itemized list of the add-on products that authorize the use of the $function.
See also:
- Using functions, which reviews coding in SOUL with $functions
- Notation conventions, which provides a description of the conventions used in syntax on individual $function pages.
$Function | Description |
---|---|
$Abbrev | Determine if string is abbreviation within list of words |
$Account | Account under which the user is logged in. |
$Acct | User ID under which the user is logged in. |
$Alpha | Whether a string is composed of only the letters A through Z. |
$AlphNum | Whether a string is composed of only the letters A through Z and digits 0 through 9. |
$Arr_Find | Find value within array |
$Arr_Init | Initialize every element of array to specific value |
$Arr_Max | Find maximum value in array |
$Arr_Min | Find minimum value in array |
$ArrSize | Number of elements in a particular dimension of an array. |
$Ascii | Input string, converted from EBCDIC to ASCII. |
$A2E | Translate ASCII to EBCDIC |
$Base64_Decode | Convert from base 64 to byte string |
$Base64_Encode | Convert byte string to base 64 |
$BgPurge | Cancel "long" sdaemon request initiated with $CommBg |
$BgQuery | List of "long" sdaemon requests initiated via $CommBg |
$Binary | A number converted into fixed-point binary. |
$Bind_List | Return list of bound semaphores onto a $list |
$Bind | Fast, easy synchronization of system wide resource |
$BitAnd | Bitwise AND of two integers |
$BitOr | Bitwise OR of two integers |
$BldProc | Enables a request to build a temporary procedure. |
$Buffer_Position | Current Universal Buffer position. |
$Buffer_Size | Size of user's Universal Buffer. |
$Buffer_Used | Amount of data currently in Universal Buffer |
$Bump | Bump a user |
$CenqCt | Number of unused entries within the resource enqueuing table. |
$Center | Center string |
$CfStatL | List of statistics for users holding critical file resources |
$ChkMod | Whether the terminal operator entered data in any full-screen input field. |
$ChkPat | Syntax of a pattern. |
$ChkpInf | Information about checkpoints |
$ChkTag | Whether any erroneous full-screen input has been entered by the end user. |
$Close | Close file or group in User Language request |
$Cms | Determine if online is running under CMS |
$Code | Encoding facility. |
$Command | Execute Model 204 command on sdaemon, results to image |
$CommBg | Execute Model 204 commands on sdaemon |
$CommndL | Execute Model 204 command on sdaemon, results to $list |
$Context | Determine if string is name of open file or group |
$Curfile | Name of the file from which the current record has been selected. |
$Currec | Integer equal to the internal number of the current record. |
$C2D | Convert binary byte string to integer |
$C2X | A translation of each byte within a character string to its two-byte hexadecimal representation. |
$DaemonMasterNumber | Get user number of master thread |
$DaemonParentNumber | Get user number of parent thread |
$Date | Current date in yy-mm-dd format. |
$DateChg | Specified number of days, added to or subtracted from a given date. |
$DateChk | Whether a given date is valid. |
$DateCnv | Date converted to a format specified by the user. |
$DateDif | Difference in days between two dates. |
$DateJ | Current date in "yy.ddd" format. |
$DateP | Current date in "dd mon yy" format. |
$DAY | Day name of the input day-number. |
$DayI | Number reflecting current day of the week. |
$Deblank | Substring of a string, with leading and trailing blanks removed. |
$Decode | Decoding facility. |
$Deflate | Compress a longstring with Deflate |
$DelCh | Remove characters from string, compress and strip blanks |
$Delg_Subsys | Delete subsystem-wide global |
$Delg_Sys | Delete system-wide global |
$Delimr | Insert delimiter string into input string at regular positions |
$Dscr | Decoding facility. |
$Dsn | Data set name when you specify a file's DD name and the ordinal number. |
$DsnNum | Total number of data sets defined for a file when you specify the file's DD name. |
$D2C | Binary byte representation of integer |
$D2X | Hex representation of integer |
$Ebcdic | Convert input string from ASCII to EBCDIC |
$EcbDGet | Get string data associated with an Event Control Block (ECB) |
$EcbDSet | Set string data associated with an Event Control Block (ECB) |
$EcbTest | Check an Event Control Block (ECB) to see if it is posted |
$EcfStat | Returns the detailed completion code from the previous EXTERNAL statement. |
$Edit | Edited numeric and alphanumeric text |
$EdScan | Scan list of entities in online |
$Eformat | Exponent notations from converted numeric values |
$Encrypt | A one-way encryption of a character string. |
$Ent_Print | Set automatic character entity substitution |
$Ent_Tab | retrieve/modify character entity substitution table |
$Ent | Do character entity substitution |
$Enter | Efficient terminal dialogue with users of data entry applications. |
$ErrClr | Clears the error message text returned by the $ErrMsg and $Fsterr functions. |
$ErrMsg | Prefix and text of the last counting error or request cancellation message received. |
$ErrSet | Increment or clear number of counting errors, set $ErrMsg |
$E2A | Translate EBCDIC to ASCII |
$FakeEnt | Prepare fake ENTER to automatically satisfy next full screen read |
$FDef | String that describes the attributes of a field in a Model 204 file. |
$Field_Image | Return field values into an image |
$Field_List | Return field values into a $list |
$Field_ListI | Return field values into a $list mapped to an image |
$FieldgroupId | The ID of the current field group. (Available as of Model 204 version 7.5.) |
$FieldgroupOccurrence | The current occurrence number of the field group. (Available as of Model 204 version 7.5.) |
$FIniTim | File initialization YYDDDMMHHSSTH |
$FiStat | Retrieve file's statistics into string |
$FiStatL | Retrieve set of files' statistics into list |
$FldLen | Length of a field. |
$Float | Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string). |
$FloatD | Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string). |
$FlsAcc | User's access rights to a particular field. |
$FlsChk | Whether a given set of field level security accesses is valid for a field. |
$FreeOpt | Free optional file or group from subsystem |
$Fsterr | Variable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero. |
$FunForc | Cancel running or waiting Fast/Unload request |
$FunImg | Retrieve data from active Fast/Unload request into image |
$FunList | $list of active and enqueued Fast/Unload requests |
$FunLoad | Fast/Unload records in Model 204 list or found set |
$FunPurg | Purge running or waiting Fast/Unload request |
$FunSkip | Skip to next output record for $FunImg, $FunsStr |
$FunsStr | Retrieve data from active Fast/Unload request into string |
$FunWait | Wait until asynchronous Fast/Unload request completes |
$Getg | Information stored by a $SETG function. |
$GetL | Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command. |
$GetP | Page number currently on the user's terminal or on the output data set specified by a USE command. |
$GrmLoc | Location of a missing member. |
$GrmName | File name of a missing member. |
$GrnLeft | Number of optional files that may fail before MAXFAIL is exceeded. |
$GrnMiss | Number of missing members. |
$GunZip | Decompress a longstring with GUNZIP |
$GZip | Compress a longstring with GZip |
$HexA | Convert hexadecimal string to EBCDIC equivalent |
$HPage | String of special characters whose length is equal to the value specified as the $HPage argument. |
$Hsh | A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value. |
$IHexA | Convert EBCDIC string to hexadecimal equivalent |
$ImgInf | Retrieve image item by variable name |
$ImgOvl | Replace image item value |
$Incrg | Performs simple arithmetic on global variables. |
$IncStat | Increment local system statistic |
$Index | After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN. |
$Inflate | Decompress a longstring with inflate |
$ItsOpen | Whether or not a file is open. |
$ItsRemote | Whether the current file or group is remote or scattered. |
$JobAuth | Determine if user has authorization for USE $JOB |
$Jobcode | Allows a request that is part of one step of a Model 204 batch run to communicate with a subsequent step. |
$JpStat | Retrieve Janus port's statistics into string |
$JpStatL | Retrieve statistics for set of Janus pors into $list |
$LangSpc | String containing the binary value of a character in a specified language. |
$LangSrt | A binary string translated to sort according to the NLSORT macro for the specified language. |
$LangUst | Previously $LangSrt'ed string translated back to its original form. |
$Len | Length of a value in a field. |
$List_Add_Ordered | Add an item to an ordered $list |
$List_Add_Unique_Ordered | Conditionally add an item to an ordered $list |
$List_Add_Unique | Conditionally add an item to a $list |
$List_Capture | Capture print data to $list |
$List_Conv_Item | Convert $list to single delimited $list item |
$List_Copy_Items | Copy items between $lists |
$List_Diff_Item | Differences between $list and delimited $list item |
$List_Global and $List_Session | Access/create global/session $list |
$List_Global_Del and $List_Session_Del | Delete global/session $lists |
$List_Global_List and $List_Session_List | List global/session $lists |
$List_MaxIL | Return maximum $list item length |
$List_Print | Display contents of a $list |
$ListAdd_Lstr | Add longstring as new $list item |
$ListAdd | Add string as new $list item |
$ListAddI | Add image as new $list item |
$ListAdj | Adjust length of $list item |
$ListChk | Validate a $list identifier |
$ListCmp | Compare two $lists and produce $list describing differences |
$ListCnt | Number of items in $list |
$ListCpy | Copy $list |
$ListDel | Release CCATEMP storage used for $list |
$ListFind | Find string in $list |
$ListFindI and $ListFindI_Up | Find image item in $list |
$ListFindI_Sub | Build $list subset based on image item |
$ListILn | Length of $list item |
$Listimg_Copy | Copy a $list's image association |
$ListImg | Associate an image with a $list |
$ListInf_Lstr | Retrieve $list item into longstring |
$ListInf | Retrieve $list item into string |
$ListInfI | Retrieve $list item into image |
$ListIns_Lstr | Insert string into a $list |
$ListIns | Insert string into a $list |
$ListInsI | Insert image into a $list |
$ListLoc | Locate string in $list |
$ListLup | Locate string in $list, searching backwards |
$ListMove | Move a $list |
$ListNew | Create empty $list |
$ListNewA | Create array of empty $lists |
$ListNewAI | Create array of empty $lists associated with image |
$ListNewI | Create empty $list associated with image |
$ListOvl | Overlay part of $list item with string |
$ListOvlI | Overlay part of $list item with image item |
$ListRem | Remove item from $list |
$ListRep_Lstr | Replace a $list item with a longstring |
$ListRep | Replace a $list item with a string |
$ListRepI | Replace $list item with an image |
$ListRst | Restore global $list |
$ListSav and $ListSave | Save global $list |
$ListSavL | Count and names of available global $lists |
$ListSort and $ListSrt | Sort $list |
$ListSub | Create $list that is subset of input $list |
$ListUpd | Produce $list from input $list using $list of updates |
$Lowcase | A lower case string translated from an uppercase or mixed case string |
$LstFld | Field names in a file, along with their field descriptions, into an image. |
$LstProc | Information that is stored for a procedure. |
$Lstr_Add_UserBuffer | Add longstring to user buffer |
$Lstr_Base64_Decode | Convert from base 64 to byte string |
$Lstr_Base64_Encode | Convert byte string to base 64 |
$Lstr_C2X | Convert byte string to hexadecimal |
$Lstr_Get_Image and $Lstr_Set_Image | Longstring to/from image |
$Lstr_Get_Userbuffer | Get user buffer contents to a longstring |
$Lstr_Global and $Lstr_Session | Bind to global/session longstring |
$Lstr_Global_Del and $Lstr_Session_Del | Delete global or session longstring |
$Lstr_Global_Get and $Lstr_Session_Get | Get global or session longstring |
$Lstr_Global_Set and $Lstr_Session_Set | Set global or session longstring |
$Lstr_Index | Find a string inside a longstring |
$Lstr_Left | Leftmost characters of a longstring |
$Lstr_Len | Length of a longstring |
$Lstr_Parse | Part of longstring preceding character in delimiter set |
$Lstr_ParseX | Part of longstring following character in delimiter set |
$Lstr_Right | Rightmost characters of a longstring |
$Lstr_Set_UserBuffer | Set user buffer to longstring value |
$Lstr_Substr | Substring of a longstring |
$Lstr_SubWord | Substring of a longstring using word counts |
$Lstr_Translate | Translate longstring |
$Lstr_Unblank | Remove extraneous blanks from longstring |
$Lstr_Windex | Return the position of a word within a long string |
$Lstr_Word | Return a word from a long string |
$Lstr_Words | Return the number of words in a long string |
$Lstr_X2C | Convert from hexadecimal to byte string |
$Lstr | Treat a string as longstring |
$MisGrup | Group name if the error occurred in group context, null if in file context. |
$MisLoc | Location of a missing member or file. |
$MisName | File name of a missing member or file. |
$MisNum | Number of files that failed in a group. |
$MisStmt | Statement that caused the ON unit to be entered. |
$Mod | Remainder that results when one argument is divided by the another argument. |
$Occurs | Whether a field has the OCCURS attribute. |
$Oneof | Table lookup that can replace a series of IF conditions. |
$Pack | Packed decimal representation of a string. |
$Pad | Designated character padded to the left. |
$PadR | Designated character padded to the right |
$Parse | Part of string preceding character in delimiter set |
$ParseX | Part of string following character in delimiter set |
$Post | Indicates that an event has occurred; the thread waiting on an ECB can resume processing. |
$PrcLEx | $list of information about procedures in file |
$PrcLExG | $list of information about procedures in group or file |
$Priorty | Change a user's priority |
$Proc_List | $list of information about procedures in file |
$Proc_ListG | $list of information about procedures in group or file |
$Proc_Touch | Change a procedure's last-update date and user |
$ProcCls | Close procedure before reaching end |
$ProcDat | Add lines from procedure to $list |
$ProcGet | Next line of procedure |
$ProcLoc | Locate any of set of strings in procedure |
$ProcOpn | Open procedure for $ProcDat, $ProcGet, $ProcLoc |
$Random_Seed | Build seed specifying series of $Random results |
$Random | Get next random number |
$RdProc | Lines of a User Language procedure, retrieved in sequential order, that is stored in a Model 204 file. |
$Read | An echo of the data a user enters as a request is evaluated |
$ReadInv | Performs the same function as $READ, except that input from the terminal is not echoed. |
$ReadLc | An echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting. |
$RegexMatch | Whether string matches regex |
$RegexReplace | Replace matching strings |
$Remote | VTAMNAME value of the originating Model 204 region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between Model 204 regions. |
$ResetN | Reset or view M204 parameter |
$Reverse | Reversed order of a string. |
$RlcFile | Name of the file in which the last record locking conflict occurred. |
$RlcRec | Internal record number for which the last record locking conflict occurred. |
$RlcUid | ID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node. |
$RlcUsr | User number of the user with which the request conflicted when the last record locking conflict occurred. |
$Round | Number, rounded to a specified number of decimal places. |
$Scan | After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX. |
$Sclass | Current user's subsystem user class. |
$Screen_attr | Get screen item attributes as a blank-delimited string |
$Screen_clear | Clear tagged and/or modified attributes in a screen |
$Screen_mod | Set modified attribute for a screen item |
$ScrHide | Hide lines in SCREEN |
$ScrSize | Change size of field on SCREEN |
$ScrWide | Allow SCREEN to accept fields wider than 79 |
$Session, $Session_Id, $Session_Owner, and $Session_Timeout | Return values for currently open session |
$Session_Close | Close an open session |
$Session_Create | Create a new session |
$Session_Delete | Delete a session |
$Session_List | Get list of sessions |
$Session_Open | Open a session |
$Setg_Subsys_List | Get list of subsystem-wide globals |
$Setg_Subsys | Set subsystem-wide global |
$Setg_Sys_List | Get list of system-wide globals |
$Setg_Sys | Set system-wide global |
$Setg | A created or changed entry in the global variable section of GTBL. |
$SetL | Sets the current line counter for the output device currently in effect. |
$SetP | Sets the current page number for the output device currently in effect. |
$SetStat | Set local system statistic |
$Sir_Date | Get current datetime |
$Sir_DateFmt | Validate datetime format |
$Sir_DateN | Current date and time as number of seconds/300 |
$Sir_DateND | Current date as number of days |
$Sir_DateNM | Current date and time as number of milliseconds |
$Sir_DateNS | Current date and time as number of seconds |
$Sir_Date2N | Convert datetime string to number of seconds/300 |
$Sir_Date2ND | Convert datetime string to number of days |
$Sir_Date2NM | Convert datetime string to number of milliseconds |
$Sir_Date2NS | Convert datetime string to number of seconds |
$Sir_Login | Perform secured web or sockets login |
$Sir_ND2Date | Convert datetime number of days to string |
$Sir_NM2Date | Convert datetime number of milliseconds to string |
$Sir_NS2Date | Convert datetime number of seconds to string |
$Sir_N2Date | Convert datetime number of seconds/300 to string |
$Sir_Wild | Test string against a wildcard string |
$SirJGet | Place audit trail data on $list |
$SirMsg | Line of current $SirMsgP procedure |
$SirMsgP | Load procedure for retrieval via $SirMsg |
$SirParm | Set user-specific value, controlling Sirius products |
$SirProd | Determine availability of Sirius product or capability |
$SirSite | Current Sirius customer site ID |
$SirTime | Current time as YYDDDHHMISSXX |
$SirVer | Current version number of Sirius product |
$SirWarn | Send warning or message to user(s) |
$Slstats | Resets the recording of since-last statistics anywhere within a request. |
$SndMail | Send an email message |
$Sndx | SOUNDEX code of an argument. |
$Square | A number multiplied by itself. |
$SsStat | Retrieve subsystem's statistics into string |
$SsStatL | Retrieve statistics for set of subsystems into $list |
$Stat | Current value of any user statistic. |
$StatD | Calculate differences and rates for statistics strings |
$StatLD | Calculate differences and rates for statistics $lists |
$Status | The success or failure of the last executed external I/O or program communication statement. |
$StatusD | More detailed description of a condition returned by $STATUS. |
$Str | Treat a longstring as string |
$StrAnd | Bit-wise AND two strings |
$Strip | A number with suppressed leading zeros. |
$StrOr | Bit-wise OR two strings |
$StrXor | Bit-wise exclusive OR two strings |
$SubCnt | Count occurrences of one string in another |
$SubErs | Remove occurrence of one string from another |
$SubIns | Insert string inside another string |
$SubRep | Replace occurrences of string |
$Substr | Substring of a string. |
$Subsys | Status of an APSY subsystem. |
$SyStat | Retrieve system statistics into string |
$TableC | Information provided by TABLEC command |
$TermId | Terminal ID of current user thread |
$Time | Current time in hh:mm:ss format. |
$TkStat | Retrieve task's statistics into string |
$TkStatL | Retrieve statistics for all tasks into $list |
$TsoAtt | Attach program in user's TSO address space |
$TsoCall | Call program in user's TSO address space |
$TsoCan | Cancel program invoked via $TsoAtt |
$TsoCmd | Invoke command in user's TSO address space |
$TsoExec | Invoke CLIST in user's TSO address space |
$TsoExit | Terminate TSO full screen interface session, stack command |
$TSOId | TSO userid user's thread |
$TSOStat | Status of program invoked via $TsoAtt |
$TSOWait | Wait for program invoked via $TsoAtt to complete |
$Unbin | Value converted from binary to string representation. |
$Unbind_and_$UnbindW | $Unbind and $UnbindW: Unbind resource previously bound via $Bind |
$Unblank | Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character. |
$Unfloat | Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point. |
$Unpack | Unpacked decimal data |
$UnPost | Resets a specified Event Control Block (ECB) to an unposted state. |
$UnqRec | In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pair If no uniqueness violation occurred. returns -1. |
$UnSpace | Normalize spaces and quotes |
$Upcase | An uppercase string converted from a lower or mixed case string. |
$Update | Name of the group update file or the current file. |
$UpdFile | Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred. |
$UpdFld | Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred. |
$UpdLoc | Location name (node name) of the current update unit (Parallel Query Option/204 only). |
$UpdOval | Value of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict. |
$UpdRec | File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred. |
$UpdStat | Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred. |
$UpdStmt | Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred. |
$UpdVal | Field value causing a field level constraint violation, or a blank if no violation occurred. |
$UseASA | Prevent carriage control in USE output |
$User | User's user number. |
$Userid | User ID under which the user is logged in. |
$UsrPriv | Whether a user ID has been granted specific Model 204 privileges. |
$UsStat | Retrieve user's statistics into string |
$UsStatL | Retrieve statistics for set of users into $list |
$Verify | Whether every character in one string is present in a second string. |
$View | Value of a parameter. |
$Vnum | Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation. |
$Wait | Suspend a user until an Event Control Block (ECB) is posted. |
$WakeUp | Pause user until specified time |
$Web_xxx | List of Janus Web Server $functions |
$Windex | Word number of first occurrence of word in phrase |
$Word | P word in a specified string, delimited by a blank or optionally specified character. |
$Words | Number of words in a specified string, delimited by a blank or optionally specified character. |
$X2C | One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character. |
$X2D | Convert hex string to integer |
Using functions
You can use functions in several ways, including, as a term in:
- An expression in a variable assignment statement, for example:
%X=$EDIT(2573,'99999')
- The specifications in a PRINT statement
A PRINT statement can include a function call anywhere a field name can be used. For example:
PRINT $EDIT(2573,'99999')
- An expression in a conditional statement, for example:
IF $EDIT(2573,'99999') EQ 02573 THEN...
- An expression which serves as the argument to another function, for example:
%L=$LEN($EDIT(2573,'99999'))
The direct use of function calls in some statements, such as FIND, results in compilation errors.
Comparing successful and unsuccessful $function code
If your request is coded as follows:
BEGIN $EDIT(2573,'99999') END
The following error is your result:
*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')
However, if you code your request as follows, it works properly:
BEGIN PRINT $EDIT(2573,'99999') * Or * * %X=$EDIT(2573,'99999') * END
Function return values
Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:
%a = $account
This function causes the length of the current value of the FULLNAME field to be compared to 10:
IF $LEN(FULLNAME) GT 10 THEN . . .
Function arguments
Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:
IF $READ('CONTINUE?') EQ 'YES' THEN . . . %X = $mod(COUNT IN CT, %BASE)
Rules for function arguments
Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section Expressions for detailed information on expression syntax.
Argument evaluation and conversion
Model 204 evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:
- If an argument is expected to be numeric but is a string, Model 204 converts the string to a number according to the conversion rules described in the assignment statement discussion in Relationship between %variable assignment and declaration and Conversion.
- If an argument is expected to be a string but is numeric, Model 204 converts the number to a string.
- If the original number contains decimal places, they are lost during the conversion.
User-written functions
In addition to the functions provided by SOUL, some customer sites write their own functions based on their particular needs. Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production.
Notes:
- It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.
- The RESULT macro does not work in Model 204 Version 5.1 and later. Change any use of the RESULT macro in $functions to use the standard LEAVENUM, LEAVEF0 and LEAVESTR macros.
- In addition to the above considerations, see the installation instructions relating to FUNU.
Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.