SOUL $functions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
==Overview==
Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, <var class="product">SOUL</var> provides a variety of $functions. Many of these functions are in favor of an OO API method. When that is the case, the $function page notes the matching method.
<p>
Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, User Language provides a variety of functions, which are assembly language subroutines you can call from within a User Language request.</p>
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>[[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 OCM BOCES $functions]]</td><td>To support SIS</td></tr>-->
</table>
</div>
In addition, many of the [[#List of standard $functions|standard $functions]] contain a section titled "Products authorizing <i>$xxx</i>"; starting with version 7.5 of <var class="product">Model 204</var>, these $functions are available to all customers.
==List of standard $functions==
<p>
<p>
The name of each User Language function begins with a dollar sign ($). For this reason, they are often referred to as $functions (dollar functions).</p>
   
   
==Types of functions==
The following table lists the standard <var class="product">SOUL</var> $functions in alphabetical order. </p>
   
   
===Functions provided by User Language===
<p>
<p>
The functions provided by User Language are divided into two sets. One set is supplied as a standard feature and includes functions for data editing, data validation, and other purposes. The other set of functions (mathematical functions) is an optional feature of <var class="product">Model&nbsp;204</var> and contains mathematical and scientific subroutines.    </p>
<p>
In order to save machine resources, your site might have chosen to omit some of the standard functions as well as some or all of the mathematical functions. If a request calls a function that is not yet installed, compile-time errors result. </p>
   
   
===User-written functions===
See also [[#Using_functions|"Using functions"]], which reviews coding in <var class="product">SOUL</var> with $functions.</p>
<p>
In addition to the functions provided by User Language, some customer sites write their own functions based on their particular needs.</p>
<div class="showVisit">
<p>
<table class="wikitable">
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>
<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>[[$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>[[$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>[[$DateP]]</td><td>Current date in "dd mon yy" format.</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>[[$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&nbsp;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&nbsp;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>[[$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>[[$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&nbsp;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&nbsp;204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model&nbsp;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>[[$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, &nbsp;&nbsp;<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>[[$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&nbsp;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>[[$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>
   
   
<p class="note">
<b>Note:</b>
It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.</p>
<p>
Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.</p>
==Using functions==
==Using functions==
<p>
You can use functions in several ways, including, as a term in:
You can use functions in several ways, including, as a term in:</p>
<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 112: Line 484:
</li>
</li>
</ul>
</ul>
 
==Sending email messages via User Language==
<div id="$SndMail">
==Sending email messages via $SndMail==
</div>
<p>
<p>
The User Language <var>$SNDMAIL</var> function simplifies sending an email message to issuing a single function call. You can easily send an email message using User Language without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.</p>
The <var class="product">SOUL</var> <var>$SndMail</var> function simplifies sending an email message to issuing a single function call. You can easily send an email message using <var class="product">SOUL</var> without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.</p>
   
   
====Internet Protocol (IP) addressing====
====Internet Protocol (IP) addressing====
Line 121: Line 495:
On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.</p>
On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.</p>
   
   
====Limitations of the $SNDMAIL function under z/VM and z/VSE====
====Limitations of $SndMail under z/VM and z/VSE====
<p>
<p>
<var>$SNDMAIL</var> is supported with the following exceptions:</p>
<var>$SndMail</var> is supported with the following exceptions:</p>
<ul>
<ul>
<li>The <var>[[SMTPCADD parameter|SMTPCADD]]</var> and <var>[[SMTPSADD parameter|SMTPSADD]]</var> addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the <var>SMTPCADD</var> and <var>SMTPSADD</var> parameters.</li>
<li>The <var>[[SMTPCADD parameter|SMTPCADD]]</var> and <var>[[SMTPSADD parameter|SMTPSADD]]</var> addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the <var>SMTPCADD</var> and <var>SMTPSADD</var> parameters.</li>
 
<li>Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters <var>SMTPCADD</var> and <var>SMTPSADD</var>, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values. </li>
<li>Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters <var>SMTPCADD</var> and <var>SMTPSADD</var>, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values. </li>
 
<li><var class="product">Model&nbsp;204</var> does not support IPv6 addressing on z/VM or z/VSE systems.</li>
<li><var class="product">Model&nbsp;204</var> does not support IPv6 addressing on z/VM or z/VSE systems.</li>
</ul>
</ul>
   
   
===Enabling $SNDMAIL===
===Enabling $SndMail===
<p>
<p>
The first requirement for enabling the use of $SNDMAIL is to set the following four required CCAIN parameters:</p>
The first requirement for enabling the use of $SndMail is to set the following four required CCAIN parameters:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 140: Line 514:
<th>SMTP purpose</th>
<th>SMTP purpose</th>
</tr>
</tr>
 
<tr>
<tr>
<td>SMTPCADD</td>
<td>SMTPCADD</td>
<td>SMTP client address. The client is the <var class="product">Model&nbsp;204</var> address space.  
<td>SMTP client address. The client is the <var class="product">Model&nbsp;204</var> address space.
<p>
<p>
On z/OS systems:</p>
On z/OS systems:</p>
Line 150: Line 524:
<ul>
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>
 
<li>Dotted decimal address, such as 182.148.55.206.</li>
<li>Dotted decimal address, such as 182.148.55.206.</li>
 
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>
</ul>
Line 161: Line 535:
</td>
</td>
</tr>
</tr>
 
<tr>
<tr>
<td>SMTPCPRT</td>
<td>SMTPCPRT</td>
<td>SMTP client port. The default value is 7700.</td>
<td>SMTP client port. The default value is 7700.</td>
</tr>
</tr>
 
<tr>
<tr>
<td>SMTPSADD</td>
<td>SMTPSADD</td>
Line 176: Line 550:
<ul>
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>
 
<li>Dotted decimal address, such as 182.148.55.206.</li>
<li>Dotted decimal address, such as 182.148.55.206.</li>
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>.</li>
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>.</li>
Line 186: Line 560:
</td>
</td>
</tr>
</tr>
 
<tr>
<tr>
<td>SMTPSPRT</td>
<td>SMTPSPRT</td>
Line 192: Line 566:
</tr>
</tr>
</table>
</table>
 
<p>
<p>
Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either <var>SMTPCADD</var> or <var>SMTPSADD</var>, you must have the following DD allocated to the Online:</p>
Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either <var>SMTPCADD</var> or <var>SMTPSADD</var>, you must have the following DD allocated to the Online:</p>
Line 200: Line 574:
This is the TCP/IP profile data set required to support the resolution of IP domain names. </p>
This is the TCP/IP profile data set required to support the resolution of IP domain names. </p>
<p>
<p>
On some SMTP servers, a valid email address is required for the <var class="term">%from</var> argument in the <var>$SNDMAIL</var> function. Most SMTP activity requires a valid SMTP server.</p>
On some SMTP servers, a valid email address is required for the <var class="term">%from</var> argument in the <var>$SndMail</var> function. Most SMTP activity requires a valid SMTP server.</p>
   
   
====$SNDMAIL and BATCH204====
====$SndMail and BATCH204====
<p>
<p>
<var>$SNDMAIL</var> is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:</p>
<var>$SndMail</var> is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:</p>
<ul>
<ul>
<li>TC62 (or TC62DOS on z/VSE systems)</li>
<li>TC62 (or TC62DOS on z/VSE systems)</li>
 
<li>TCIU</li>
<li>TCIU</li>
 
<li>TCSE</li>
<li>TCSE</li>
 
<li>LU62</li>
<li>LU62</li>
 
<li>FUNR (or FUNRDOS on z/VSE systems)</li>
<li>FUNR (or FUNRDOS on z/VSE systems)</li>
</ul>
</ul>
Line 220: Line 594:
<ul>
<ul>
<li>SMTPCADD</li>
<li>SMTPCADD</li>
 
<li>SMTPSADD</li>
<li>SMTPSADD</li>
 
<li>SMTPCPRT</li>
<li>SMTPCPRT</li>
 
<li>SMTPSPRT</li>
<li>SMTPSPRT</li>
</ul>
</ul>
   
   
===$SNDMAIL===
===$SndMail syntax===
<p>
<p>
The <var>$SNDMAIL</var> function sends an email message using the values you enter for the <var>$SNDMAIL</var> arguments. <var>$SNDMAIL</var> lets you send an email message with an optional attachment.</p>
The <var>$SndMail</var> function sends an email message using the values you enter for the <var>$SndMail</var> arguments. <var>$SndMail</var> lets you send an email message with an optional attachment.</p>
====Syntax====
<p>
<p>
The syntax for the <var>$SNDMAIL</var> function is:</p>
The syntax for the <var>$SndMail</var> function is:</p>
<p class="syntax">$SNDMAIL(%SUBJ,%RCPT,%BODY,%FROM,%TO,%CC,%BCC,'EMAILD',%ATTACH,'C')
<p class="syntax">$SndMail(%subj, %rcpt, %body, %from, %to, %cc, %bcc, 'EMAILD', %attach, 'C')
</p>
</p>
<p>
<p>
Line 241: Line 613:
<ul>
<ul>
<li>%SUBJ, which is optional, specifies a %variable or literal that contains the topic line.</li>
<li>%SUBJ, which is optional, specifies a %variable or literal that contains the topic line.</li>
 
<li>%RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.  
<li>%RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.
<p>
<p>
If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments. </p>
If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments. </p>
Line 248: Line 620:
If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.</p>
If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.</p>
</li>
</li>
 
<li>%BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.</li>
<li>%BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.</li>
 
<li>%FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.</li>
<li>%FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.</li>
 
<li>%TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.
<li>%TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.
<p>
<p>
Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.</p>
Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.</p>
</li>
</li>
 
<li>'EMAILD', which is optional, specifies image data.  The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD.  If 'EMAILD' is present, it must be in the following format, with the items in the following order:  
<li>'EMAILD', which is optional, specifies image data.  The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD.  If 'EMAILD' is present, it must be in the following format, with the items in the following order:
<p class="code">* EMAILD - IMAGE WITH SMTP PARAMETERS
<p class="code">* EMAILD - IMAGE WITH SMTP PARAMETERS
IMAGE EMAILD                                                                    
IMAGE EMAILD
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT                                              
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT                                              
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD                                            
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD                                          
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD
     SERVERDD      IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional)            
     SERVERDD      IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional)
     CLIENTDD      IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional)          
     CLIENTDD      IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional)
     SERVERIPV6    IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional)  
     SERVERIPV6    IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional)
     CLIENTIPV6    IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional)  
     CLIENTIPV6    IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional)
END IMAGE                                                                        
END IMAGE
</p>
</p>
<p>
<p>
The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.</p>
The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.</p>
</li>
</li>
 
<li>%ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.
<li>%ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.
<p>
<p>
The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.</p></li>
The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.</p></li>
 
<li>'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SNDMAIL attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document.  If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.
<li>'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SndMail attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document.  If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.
<p>
<p>
In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:</p>
In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:</p>
<p class="code">%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')
<p class="code">%RC = $SndMail(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')
</p>
</p>
</li>
</li>
</ul>
</ul>
 
===Setting CCAIN parameters for $SNDMAIL===
===Setting CCAIN parameters for $SndMail===
<p>
<p>
You can set the following CCAIN parameters as default values for $SNDMAIL.</p>
You can set the following CCAIN parameters as default values for $SndMail.</p>
<ul>
<ul>
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for $SndMail. You can sp            ecify SMTPCADD as:
<ul>
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </li>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </li>
 
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
 
<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:
<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>
</ul>
<p>
<p>
You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p></li>
You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.</p></li>
 
<li>SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range &mdash; normally above 4095 and up to 32767.
<li>SMTPCPRT is the default SMTP client port for the $SndMail function. The value can be any value in the user range &mdash; normally above 4095 and up to 32767.
<p>
<p>
You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.</p>
</li>
</li>
 
<li>SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:
<li>SMTPSADD is the default SMTP server address for $SndMail. You can specify SMTPSADD as:
<ul>
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</li>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</li>
 
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
 
<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>
</ul>
<p>
<p>
You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.</p>
</li>
</li>
 
<li>SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.</li>
<li>SMTPSPRT is the default SMTP server port for $SndMail. SMTPSPRT is normally set to the standard SMTP value of 25.             You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of $SndMail.</li>
</ul>
</ul>
 
===Examples of running $SNDMAIL===
===Examples of running $SndMail===
   
   
====Example 1====
====Example 1====
Line 329: Line 701:
%TO    = 'My Friend <you@yourdomain.com>'
%TO    = 'My Friend <you@yourdomain.com>'
%BNAME = 'mypicture.jpg'
%BNAME = 'mypicture.jpg'
 
MODIFY BUFFER CLEAR
MODIFY BUFFER CLEAR
 
IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY
IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY
   %ISIZE = $LOBLEN(SVRLOB)
   %ISIZE = $LOBLEN(SVRLOB)
Line 337: Line 709:
   BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE
   BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE
END FOR
END FOR
 
PRINT 'BUFFER USED IS ' WITH $buffer_used
PRINT 'BUFFER USED IS ' WITH $buffer_used
%SUBJECT  = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY
%SUBJECT  = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY
Line 344: Line 716:
</p>
</p>
<p>
<p>
In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. The $SNDMAIL function sends this as a Base64-encoded attachment.</p>
In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer.
$SndMail sends this as a Base64-encoded attachment.</p>
<p class="note"><b>Note:</b> The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.</p>
<p class="note"><b>Note:</b> The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.</p>
 
====Example 2====
====Example 2====
<p class="code">%TO  ='JANE <YOU@YOURCORP.COM>'
<p class="code">%TO  ='JANE <YOU@YOURCORP.COM>'
Line 357: Line 730:
The EMAILD argument is used to override the default domain names and ports.</p>
The EMAILD argument is used to override the default domain names and ports.</p>
<p class="code">IMAGE EMAILD
<p class="code">IMAGE EMAILD
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT                                              
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT                                              
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD                                            
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD                                          
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD
   END IMAGE
   END IMAGE
   
   
Line 389: Line 762:
   %RC        = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')
   %RC        = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')
</p>
</p>
 
====Example 4====
====Example 4====
<p>
<p>
This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.</p>
This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.</p>
<p class="code">IMAGE EMAILD
<p class="code">IMAGE EMAILD
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT                                              
     SERVERPORT    IS BINARY LEN 4    ;*SMTPSPRT
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT                                              
     CLIENTPORT    IS BINARY LEN 4    ;*SMTPCPRT
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD                                            
     SERVERNAME    IS STRING LEN 255  ;*SMTPSADD
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD                                          
     CLIENTNAME    IS STRING LEN 255  ;*SMTPCADD
     SERVERDD      IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional)            
     SERVERDD      IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional)
     CLIENTDD      IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional)          
     CLIENTDD      IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional)
     SERVERIPV6    IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional)  
     SERVERIPV6    IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional)
     <b>CLIENTIPV6    IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional)</b>  
     <b>CLIENTIPV6    IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional)</b>
END IMAGE                                                                        
END IMAGE
   
   
PREPARE IMAGE EMAILD
PREPARE IMAGE EMAILD
Line 409: Line 782:
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
<b>%EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01'</b>
<b>%EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01'</b>
 
%FROM = 'ME@MYCORP.COM'
%FROM = 'ME@MYCORP.COM'
%TO = 'JANE <YOU@YOURCORP.COM>'
%TO = 'JANE <YOU@YOURCORP.COM>'
Line 431: Line 804:
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')
</p>
</p>
 
===ASCII translation===
===ASCII translation===
<p>
<p>
Line 442: Line 815:
===Reserved names===
===Reserved names===
<p>
<p>
The $SNDMAIL function uses Interface names CCAEM000 through CCAEM999. The user does not specify these names &mdash; the link name is generated by the function.</p>
$SndMail uses Interface names CCAEM000 through CCAEM999. The user does not specify these names &mdash; the link name is generated by the function.</p>
   
   
===Socket limits===
===Socket limits===
Line 454: Line 827:
===Return code===
===Return code===
<p>
<p>
The $SNDMAIL function returns a fixed full word binary return code. See [[#Handling error condition return codes|Handling error condition return codes]] for possible values.</p>
$SndMail returns a fixed full word binary return code. See [[#Handling error condition return codes|Handling error condition return codes]] for possible values.</p>
   
   
===RCPTTO parameter===
===RCPTTO parameter===
<p>
<p>
If the $SNDMAIL EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.</p>
If the $SndMail EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.</p>
<p>
<p>
The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.</p>
The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.</p>
Line 494: Line 867:
</ul>
</ul>
   
   
===Error codes for $SNDMAIL===
===Error codes for $SndMail===
<p>
<p>
The $SNDMAIL function issues a return code. An error in $SNDMAIL gives a return code of -1, and it is $StatusD that contains the error code. </p>
$SndMail issues a return code. An error in $SndMail gives a return code of -1, and it is $StatusD that contains the error code. </p>
<p>
<p>
The negative error codes starting with -999 are listed in [[#Handling error condition return codes|Handling error condition return codes]]. </p>
The negative error codes starting with -999 are listed in [[#Handling error condition return codes|Handling error condition return codes]]. </p>
<p>
<p>
It is also possible that $SNDMAIL will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.</p>
It is also possible that $SndMail will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.</p>
<p>
<p>
However, in the case of a non-zero (error) return code, the following message is issued to the user:</p>
However, in the case of a non-zero (error) return code, the following message is issued to the user:</p>
<p class="code">M204.2799: $SNDMAIL ERROR errortext
<p class="code">M204.2799: $SndMail error errortext
</p>
</p>
<p>
<p>
Line 512: Line 885:
<b></b>*** 1  M204.1123: PARAMETER SMTPCADD NOT RESET
<b></b>*** 1  M204.1123: PARAMETER SMTPCADD NOT RESET
</p>
</p>
 
===Handling error condition return codes===
===Handling error condition return codes===
<p>
<p>
Line 655: Line 1,028:
   
   
For the other error codes above, the following error message is returned, in addition to $StatusD being set.</p>
For the other error codes above, the following error message is returned, in addition to $StatusD being set.</p>
<p class="code">M204.2799: '$SNDMAIL ERROR %C'
<p class="code">M204.2799: '$SndMail error errorText'
</p>
</p>
<p>
<p>
Line 722: Line 1,095:
</tr>
</tr>
</table>
</table>
==Summary of standard functions==
<p>
The following table lists the standard <var class="product">SOUL</var> functions in alphabetical order. </p>
   
   
==User-written functions==
<p>
<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>
   
   
See also:</p>
<p class="note">
<ul>
<b>Note:</b>
<li>[[SOUL $functions#Using_functions|Using functions]] reviews coding in <var class="product">SOUL</var> with $functions.
It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.</p>
<li>[[List of $functions]] contains the many additional $functions available as of version 7.5 of <var class="product">Model 204</var>.
</ul>
<table>
<tr class="head">
<th>Function</th>
<th>Returns...</th>
</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>[[$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>[[$Binary]]</td>
<td>A number converted into fixed-point binary.</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>[[$CenqCt]]</td>
<td>Number of unused entries within the resource enqueuing table.</td>
</tr>
<tr>
<td>[[$ChkMod]]</td>
<td>Whether the terminal operator entered data in any full-screen input field.</td>
</tr>
<tr>
<td>[[$ChkTag]]</td>
<td>Whether any erroneous full-screen input has been entered by the end user.</td>
</tr>
<tr>
<td>[[$ChkPat]]</td>
<td>Syntax of a pattern.</td>
</tr>
<tr>
<td>[[$Code]]</td>
<td>Encoding facility.</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>[[$C2X]]</td>
<td>A translation of each byte within a character string to its two-byte
hexadecimal representation.</td>
</tr>
<tr>
<td>[[$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>[[$DateP]]</td>
<td>Current date in "dd mon yy" format.</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>[[$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>[[$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>[[$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>[[$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>
<tr>
<td>[[$Errmsg]]</td>
<td>Prefix and text of the last counting error or request cancellation message received.</td>
</tr>
<tr>
<td>[[$FDef]]</td>
<td>String that describes the attributes of a field in a <var class="product">Model&nbsp;204</var> file.</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>[[$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>[[$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>[[$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>[[$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>[[$Incrg]]</td>
<td>Performs simple arithmetic on global variables.</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>[[$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>[[$Jobcode]]</td>
<td>Allows a request that is part of one step of a <var class="product">Model&nbsp;204</var> batch run to communicate with a subsequent step.</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>[[$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>[[$MisGrup]]</td>
<td>Group name if the error occurred in group context, null if in file context.</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>[[$MisLoc]]</td>
<td>Location of a missing member or file.</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>[[$RdProc]]</td>
<td>Lines of a User Language procedure, retrieved in sequential order, that is stored in a <var class="product">Model&nbsp;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>[[$Remote]]</td>
<td>VTAMNAME value of the originating <var class="product">Model&nbsp;204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model&nbsp;204</var> regions.</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>[[$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>[[$Slstats]]</td>
<td>Resets the recording of since-last statistics anywhere within a request.</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>[[$Stat]]</td>
<td>Current value of any user statistic.</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>[[$Strip]]</td>
<td>A number with suppressed leading zeros.</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>[[$Time]]</td>
<td>Current time in hh:mm:ss format.</td>
</tr>
<tr>
<td>[[$Unbin]]</td>
<td>Value converted from binary to string representation.</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>[[$UnqRec]]</td>
<td>
<p>
<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>[[$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>[[$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>[[$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>[[$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>[[$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&nbsp;204</var> privileges.</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>[[$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>
</table>
   
   
[[Category:SOUL]]
Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.</p>

Revision as of 06:21, 2 August 2014

Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, SOUL provides a variety of $functions. Many of these functions are 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 setDescription
$xxxmathMathematical $functions
$Ftp_xxxJanus FTP Server $functions
$Sock_xxxJanus Sockets $functions
$Web_xxxJanus Web Server $functions

In addition, many of the standard $functions contain a section titled "Products authorizing $xxx"; starting with version 7.5 of Model 204, these $functions are available to all customers.

List of standard $functions

The following table lists the standard SOUL $functions in alphabetical order.

See also "Using functions", which reviews coding in SOUL with $functions.

$FunctionDescription
$AbbrevDetermine if string is abbreviation within list of words
$AccountAccount under which the user is logged in.
$AcctUser ID under which the user is logged in.
$AlphaWhether a string is composed of only the letters A through Z.
$AlphNumWhether a string is composed of only the letters A through Z and digits 0 through 9.
$Arr_FindFind value within array
$Arr_InitInitialize every element of array to specific value
$Arr_MaxFind maximum value in array
$Arr_MinFind minimum value in array
$ArrSizeNumber of elements in a particular dimension of an array.
$AsciiInput string, converted from EBCDIC to ASCII.
$A2ETranslate ASCII to EBCDIC
$Base64_DecodeConvert from base 64 to byte string
$Base64_EncodeConvert byte string to base 64
$BgPurgeCancel "long" sdaemon request initiated with $CommBg
$BgQueryList of "long" sdaemon requests initiated via $CommBg
$BinaryA number converted into fixed-point binary.
$Bind_ListReturn list of bound semaphores onto a $list
$BindFast, easy synchronization of system wide resource
$BitAndBitwise AND of two integers
$BitOrBitwise OR of two integers
$BldProcEnables a request to build a temporary procedure.
$Buffer_PositionCurrent Universal Buffer position.
$Buffer_SizeSize of user's Universal Buffer.
$Buffer_UsedAmount of data currently in Universal Buffer
$BumpBump a user
$CenqCtNumber of unused entries within the resource enqueuing table.
$CenterCenter string
$CfStatLList of statistics for users holding critical file resources
$ChkModWhether the terminal operator entered data in any full-screen input field.
$ChkPatSyntax of a pattern.
$ChkTagWhether any erroneous full-screen input has been entered by the end user.
$CloseClose file or group in User Language request
$CmsDetermine if online is running under CMS
$CodeEncoding facility.
$CommandExecute Model 204 command on sdaemon, results to image
$CommBgExecute Model 204 commands on sdaemon
$CommndLExecute Model 204 command on sdaemon, results to $list
$ContextDetermine if string is name of open file or group
$CurfileName of the file from which the current record has been selected.
$CurrecInteger equal to the internal number of the current record.
$C2DConvert binary byte string to integer
$C2XA translation of each byte within a character string to its two-byte hexadecimal representation.
$DaemonMasterNumberGet user number of master thread
$DaemonParentNumberGet user number of parent thread
$DateCurrent date in yy-mm-dd format.
$DateChgSpecified number of days, added to or subtracted from a given date.
$DateChkWhether a given date is valid.
$DateCnvDate converted to a format specified by the user.
$DateDifDifference in days between two dates.
$DatePCurrent date in "dd mon yy" format.
$DayINumber reflecting current day of the week.
$DeblankSubstring of a string, with leading and trailing blanks removed.
$DecodeDecoding facility.
$DeflateCompress a longstring with Deflate
$DelChRemove characters from string, compress and strip blanks
$Delg_SubsysDelete subsystem-wide global
$Delg_SysDelete system-wide global
$DelimrInsert delimiter string into input string at regular positions
$DscrDecoding facility.
$DsnData set name when you specify a file's DD name and the ordinal number.
$DsnNumTotal number of data sets defined for a file when you specify the file's DD name.
$D2CBinary byte representation of integer
$D2XHex representation of integer
$EcfStatReturns the detailed completion code from the previous EXTERNAL statement.
$EditEdited numeric and alphanumeric text
$EdScanScan list of entities in online
$EformatExponent notations from converted numeric values
$EncryptA one-way encryption of a character string.
$Ent_PrintSet automatic character entity substitution
$Ent_Tabretrieve/modify character entity substitution table
$EntDo character entity substitution
$EnterEfficient terminal dialogue with users of data entry applications.
$ErrClrClears the error message text returned by the $Errmsg and $Fsterr functions.
$ErrmsgPrefix and text of the last counting error or request cancellation message received.
$ErrSetIncrement or clear number of counting errors, set $ERRMSG
$E2ATranslate EBCDIC to ASCII
$FakeEntPrepare fake ENTER to automatically satisfy next full screen read
$FDefString that describes the attributes of a field in a Model 204 file.
$Field_ImageReturn field values into an image
$Field_ListReturn field values into a $list
$Field_ListIReturn field values into a $list mapped to an image
$FieldgroupIdThe ID of the current field group. (Available as of Model 204 version 7.5.)
$FieldgroupOccurrenceThe current occurrence number of the field group. (Available as of Model 204 version 7.5.)
$FIniTimFile initialization YYDDDMMHHSSTH
$FiStatRetrieve file's statistics into string
$FiStatLRetrieve set of files' statistics into list
$FldLenLength of a field.
$FloatFloating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).
$FloatDFloating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string).
$FlsAccUser's access rights to a particular field.
$FlsChkWhether a given set of field level security accesses is valid for a field.
$FreeOptFree optional file or group from subsystem
$FsterrVariable-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.
$FunForcCancel running or waiting Fast/Unload request
$FunImgRetrieve data from active Fast/Unload request into image
$FunList$list of active and enqueued Fast/Unload requests
$FunLoadFast/Unload records in Model 204 list or found set
$FunPurgPurge running or waiting Fast/Unload request
$FunSkipSkip to next output record for $FunImg, $FunsStr
$FunsStrRetrieve data from active Fast/Unload request into string
$FunWaitWait until asynchronous Fast/Unload request completes
$GetgInformation stored by a $SETG function.
$GetLLine number of the current line on the page on the user's terminal or on the output data set specified by a USE command.
$GetPPage number currently on the user's terminal or on the output data set specified by a USE command.
$GrmLocLocation of a missing member.
$GrmNameFile name of a missing member.
$GrnLeftNumber of optional files that may fail before MAXFAIL is exceeded.
$GrnMissNumber of missing members.
$GunZipDecompress a longstring with GUNZIP
$GZipCompress a longstring with GZip
$HexAConvert hexadecimal string to EBCDIC equivalent
$HPageString of special characters whose length is equal to the value specified as the $HPage argument.
$HshA hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.
$IHexAConvert EBCDIC string to hexadecimal equivalent
$ImgInfRetrieve image item by variable name
$ImgOvlReplace image item value
$IncrgPerforms simple arithmetic on global variables.
$IncStatIncrement local system statistic
$IndexAfter 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.
$InflateDecompress a longstring with inflate
$ItsopenWhether or not a file is open.
$ItsremoteWhether the current file or group is remote or scattered.
$JobAuthDetermine if user has authorization for USE $JOB
$JobcodeAllows a request that is part of one step of a Model 204 batch run to communicate with a subsequent step.
$JpStatRetrieve Janus port's statistics into string
$LangSpcString containing the binary value of a character in a specified language.
$LangSrtA binary string translated to sort according to the NLSORT macro for the specified language.
$LangUstPreviously $LangSrt'ed string translated back to its original form.
$LenLength of a value in a field.
$List_Add_OrderedAdd an item to an ordered $list
$List_Add_Unique_OrderedConditionally add an item to an ordered $list
$List_Add_UniqueConditionally add an item to a $list
$List_CaptureCapture print data to $list
$List_Conv_ItemConvert $list to single delimited $list item
$List_Copy_ItemsCopy items between $lists
$List_Diff_ItemDifferences between $list and delimited $list item
$List_Global and $List_SessionAccess/create global/session $list
$List_Global_Del and $List_Session_DelDelete global/session $lists
$List_Global_List and $List_Session_ListList global/session $lists
$List_MaxILReturn maximum $list item length
$List_PrintDisplay contents of a $list
$ListAdd_LstrAdd longstring as new $list item
$ListAddAdd string as new $list item
$ListAddIAdd image as new $list item
$ListAdjAdjust length of $list item
$ListChkValidate a $list identifier
$ListCmpCompare two $lists and produce $list describing differences
$ListCntNumber of items in $list
$ListCpyCopy $list
$ListDelRelease CCATEMP storage used for $list
$ListFindFind string in $list
$ListFindI and $ListFindI_UpFind image item in $list
$ListFindI_SubBuild $list subset based on image item
$ListILnLength of $list item
$Listimg_CopyCopy a $list's image association
$ListImgAssociate an image with a $list
$ListInf_LstrRetrieve $list item into longstring
$ListInfRetrieve $list item into string
$ListInfIRetrieve $list item into image
$ListIns_LstrInsert string into a $list
$ListInsInsert string into a $list
$ListInsIInsert image into a $list
$ListLocLocate string in $list
$ListLupLocate string in $list, searching backwards
$ListMoveMove a $list
$ListNewCreate empty $list
$ListNewACreate array of empty $lists
$ListNewAICreate array of empty $lists associated with image
$ListNewICreate empty $list associated with image
$ListOvlOverlay part of $list item with string
$ListOvlIOverlay part of $list item with image item
$ListRemRemove item from $list
$ListRep_LstrReplace a $list item with a longstring
$ListRepReplace a $list item with a string
$ListRepIReplace $list item with an image
$ListRstRestore global $list
$ListSav and $ListSaveSave global $list
$ListSavLCount and names of available global $lists
$ListSort and $ListSrtSort $list
$ListSubCreate $list that is subset of input $list
$ListUpdProduce $list from input $list using $list of updates
$LowcaseA lower case string translated from an uppercase or mixed case string
$LstFldField names in a file, along with their field descriptions, into an image.
$LstProcInformation that is stored for a procedure.
$Lstr_Add_UserBufferAdd longstring to user buffer
$Lstr_Base64_DecodeConvert from base 64 to byte string
$Lstr_Base64_EncodeConvert byte string to base 64
$Lstr_C2XConvert byte string to hexadecimal
$Lstr_Get_Image and $Lstr_Set_ImageLongstring to/from image
$Lstr_Get_UserbufferGet user buffer contents to a longstring
$Lstr_Global and $Lstr_SessionBind to global/session longstring
$Lstr_Global_Del and $Lstr_Session_DelDelete global or session longstring
$Lstr_Global_Get and $Lstr_Session_GetGet global or session longstring
$Lstr_Global_Set and $Lstr_Session_SetSet global or session longstring
$Lstr_IndexFind a string inside a longstring
$Lstr_LeftLeftmost characters of a longstring
$Lstr_LenLength of a longstring
$Lstr_ParsePart of longstring preceding character in delimiter set
$Lstr_ParseXPart of longstring following character in delimiter set
$Lstr_RightRightmost characters of a longstring
$Lstr_Set_UserBufferSet user buffer to longstring value
$Lstr_SubstrSubstring of a longstring
$Lstr_SubWordSubstring of a longstring using word counts
$Lstr_TranslateTranslate longstring
$Lstr_UnblankRemove extraneous blanks from longstring
$Lstr_WindexReturn the position of a word within a long string
$Lstr_WordReturn a word from a long string
$Lstr_WordsReturn the number of words in a long string
$Lstr_X2CConvert from hexadecimal to byte string
$LstrTreat a string as longstring
$MisGrupGroup name if the error occurred in group context, null if in file context.
$MisLocLocation of a missing member or file.
$MisNameFile name of a missing member or file.
$MisNumNumber of files that failed in a group.
$MisStmtStatement that caused the ON unit to be entered.
$ModRemainder that results when one argument is divided by the another argument.
$OccursWhether a field has the OCCURS attribute.
$OneofTable lookup that can replace a series of IF conditions.
$PackPacked decimal representation of a string.
$PadDesignated character padded to the left.
$PadRDesignated character padded to the right
$ParsePart of string preceding character in delimiter set
$ParseXPart of string following character in delimiter set
$PrcLEx$list of information about procedures in file
$PrcLExG$list of information about procedures in group or file
$PriortyChange 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_TouchChange a procedure's last-update date and user
$ProcClsClose procedure before reaching end
$ProcDatAdd lines from procedure to $list
$ProcGetNext line of procedure
$ProcLocLocate any of set of strings in procedure
$ProcOpnOpen procedure for $ProcDat, $ProcGet, $ProcLoc
$Random_SeedBuild seed specifying series of $Random results
$RandomGet next random number
$RdProcLines of a User Language procedure, retrieved in sequential order, that is stored in a Model 204 file.
$ReadAn echo of the data a user enters as a request is evaluated
$ReadInvPerforms the same function as $READ, except that input from the terminal is not echoed.
$ReadLcAn 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.
$RegexMatchWhether string matches regex
$RegexReplaceReplace matching strings
$RemoteVTAMNAME value of the originating Model 204 region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between Model 204 regions.
$ResetnReset or view M204 parameter
$ReverseReversed order of a string.
$RlcFileName of the file in which the last record locking conflict occurred.
$RlcRecInternal record number for which the last record locking conflict occurred.
$RlcUidID 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.
$RlcUsrUser number of the user with which the request conflicted when the last record locking conflict occurred.
$RoundNumber, rounded to a specified number of decimal places.
$ScanAfter 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.
$SclassCurrent user's subsystem user class.
$ScrHideHide lines in SCREEN
$ScrSizeChange size of field on SCREEN
$ScrWideAllow SCREEN to accept fields wider than 79
$Session, $Session_Id, $Session_Owner,   
and $Session_Timeout
Return values for currently open session
$Session_CloseClose an open session
$Session_CreateCreate a new session
$Session_DeleteDelete a session
$Session_ListGet list of sessions
$Session_OpenOpen a session
$Setg_Subsys_ListGet list of subsystem-wide globals
$Setg_SubsysSet subsystem-wide global
$Setg_Sys_ListGet list of system-wide globals
$Setg_SysSet system-wide global
$SetgA created or changed entry in the global variable section of GTBL.
$SetLSets the current line counter for the output device currently in effect.
$SetPSets the current page number for the output device currently in effect.
$SetStatSet local system statistic
$Sir_Date
Get current datetime
$Sir_DateFmtValidate datetime format
$Sir_DateN
Current date and time as number of seconds/300
$Sir_DateNDCurrent date as number of days
$Sir_DateNMCurrent date and time as number of milliseconds
$Sir_DateNSCurrent date and time as number of seconds
$Sir_Date2NConvert datetime string to number of seconds/300
$Sir_Date2NDConvert datetime string to number of days
$Sir_Date2NMConvert datetime string to number of milliseconds
$Sir_Date2NSConvert datetime string to number of seconds
$Sir_LoginPerform secured web or sockets login
$Sir_ND2DateConvert datetime number of days to string
$Sir_NM2DateConvert datetime number of milliseconds to string
$Sir_NS2DateConvert datetime number of seconds to string
$Sir_N2DateConvert datetime number of seconds/300 to string
$Sir_WildTest string against a wildcard string
$SirJGetPlace audit trail data on $list
$SirMsgLine of current $SirMsgP procedure
$SirMsgPLoad procedure for retrieval via $SirMsg
$SirParmSet user-specific value, controlling Sirius products
$SirProdDetermine availability of Sirius product or capability
$SirSiteCurrent Sirius customer site ID
$SirTimeCurrent time as YYDDDHHMISSXX
$SirVerCurrent version number of Sirius product
$SirWarnSend warning or message to user(s)
$SlstatsResets the recording of since-last statistics anywhere within a request.
$SndMailSend an email message
$SndxSOUNDEX code of an argument.
$SquareA number multiplied by itself.
$SsStatRetrieve subsystem's statistics into string
$SsStatLRetrieve statistics for set of subsystems into $list
$StatCurrent value of any user statistic.
$StatDCalculate differences and rates for statistics strings
$StatLDCalculate differences and rates for statistics $lists
$StatusThe success or failure of the last executed external I/O or program communication statement.
$StatusDMore detailed description of a condition returned by $STATUS.
$StrTreat a longstring as string
$StrAndBit-wise AND two strings
$StripA number with suppressed leading zeros.
$StrOrBit-wise OR two strings
$StrXorBit-wise exclusive OR two strings
$SubCntCount occurrences of one string in another
$SubErsRemove occurrence of one string from another
$SubInsInsert string inside another string
$SubRepReplace occurrences of string
$SubstrSubstring of a string.
$SubsysStatus of an APSY subsystem.
$SyStatRetrieve system statistics into string
$TableCInformation provided by TABLEC command
$TermIdTerminal ID of current user thread
$TimeCurrent time in hh:mm:ss format.
$TkStatRetrieve task's statistics into string
$TkStatLRetrieve statistics for all tasks into $list
$TsoAttAttach program in user's TSO address space
$TsoCallCall program in user's TSO address space
$TsoCanCancel program invoked via $TsoAtt
$TsoCmdInvoke command in user's TSO address space
$TsoExecInvoke CLIST in user's TSO address space
$TsoExitTerminate TSO full screen interface session, stack command
$TSOIdTSO userid user's thread
$TSOStatStatus of program invoked via $TsoAtt
$TSOWaitWait for program invoked via $TsoAtt to complete
$UnbinValue converted from binary to string representation.
$Unbind_and_$UnbindW$Unbind and $UnbindW: Unbind resource previously bound via $Bind
$UnblankContents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.
$UnfloatCharacter string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.
$UnpackUnpacked decimal data
$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.

$UnSpaceNormalize spaces and quotes
$UpcaseAn uppercase string converted from a lower or mixed case string.
$UpdateName of the group update file or the current file.
$UpdFileName of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.
$UpdFldName of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.
$UpdLocLocation name (node name) of the current update unit (Parallel Query Option/204 only).
$UpdOvalValue 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.
$UpdRecFile-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.
$UpdStatNumeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.
$UpdStmtType of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.
$UpdValField value causing a field level constraint violation, or a blank if no violation occurred.
$UseASAPrevent carriage control in USE output
$UserUser's user number.
$UseridUser ID under which the user is logged in.
$UsrPrivWhether a user ID has been granted specific Model 204 privileges.
$UsStatRetrieve user's statistics into string
$UsStatLRetrieve statistics for set of users into $list
$VerifyWhether every character in one string is present in a second string.
$ViewValue of a parameter.
$VnumWhether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.
$WakeUpPause user until specified time
$Web_xxxList of Janus Web Server $functions
$WindexWord number of first occurrence of word in phrase
$WordP word in a specified string, delimited by a blank or optionally specified character.
$WordsNumber of words in a specified string, delimited by a blank or optionally specified character.
$X2COne-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.
$X2DConvert 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.

Sending email messages via $SndMail

The SOUL $SndMail function simplifies sending an email message to issuing a single function call. You can easily send an email message using SOUL without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.

Internet Protocol (IP) addressing

On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.

Limitations of $SndMail under z/VM and z/VSE

$SndMail is supported with the following exceptions:

  • The SMTPCADD and SMTPSADD addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the SMTPCADD and SMTPSADD parameters.
  • Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters SMTPCADD and SMTPSADD, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values.
  • Model 204 does not support IPv6 addressing on z/VM or z/VSE systems.

Enabling $SndMail

The first requirement for enabling the use of $SndMail is to set the following four required CCAIN parameters:

Parameter SMTP purpose
SMTPCADD SMTP client address. The client is the Model 204 address space.

On z/OS systems:

Set this parameter to one of the following:

  • Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.
  • Dotted decimal address, such as 182.148.55.206.
  • IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as 182.148.55.206.

SMTPCPRT SMTP client port. The default value is 7700.
SMTPSADD SMTP server address.

On z/OS systems:

Set this parameter to one of the following:

  • Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.
  • Dotted decimal address, such as 182.148.55.206.
  • IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01.

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as 182.148.55.206.

SMTPSPRT SMTP server port. The default value is 25, which is standard for most SMTP servers.

Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either SMTPCADD or SMTPSADD, you must have the following DD allocated to the Online:

//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA),DISP=SHR

This is the TCP/IP profile data set required to support the resolution of IP domain names.

On some SMTP servers, a valid email address is required for the %from argument in the $SndMail function. Most SMTP activity requires a valid SMTP server.

$SndMail and BATCH204

$SndMail is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:

  • TC62 (or TC62DOS on z/VSE systems)
  • TCIU
  • TCSE
  • LU62
  • FUNR (or FUNRDOS on z/VSE systems)

After relinking you need to ensure that the following SMTP parameters are set in the ONLINE and BATCH204 CCAIN:

  • SMTPCADD
  • SMTPSADD
  • SMTPCPRT
  • SMTPSPRT

$SndMail syntax

The $SndMail function sends an email message using the values you enter for the $SndMail arguments. $SndMail lets you send an email message with an optional attachment.

The syntax for the $SndMail function is:

$SndMail(%subj, %rcpt, %body, %from, %to, %cc, %bcc, 'EMAILD', %attach, 'C')

Where:

  • %SUBJ, which is optional, specifies a %variable or literal that contains the topic line.
  • %RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.

    If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments.

    If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.

  • %BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.
  • %FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.
  • %TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.

    Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.

  • 'EMAILD', which is optional, specifies image data. The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD. If 'EMAILD' is present, it must be in the following format, with the items in the following order:

    * EMAILD - IMAGE WITH SMTP PARAMETERS IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD SERVERDD IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional) CLIENTDD IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional) SERVERIPV6 IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional) CLIENTIPV6 IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional) END IMAGE

    The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.

  • %ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.

    The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.

  • 'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SndMail attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document. If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.

    In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:

    %RC = $SndMail(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

Setting CCAIN parameters for $SndMail

You can set the following CCAIN parameters as default values for $SndMail.

  • SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for $SndMail. You can sp ecify SMTPCADD as:
    • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
    • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
    • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

    You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

  • SMTPCPRT is the default SMTP client port for the $SndMail function. The value can be any value in the user range — normally above 4095 and up to 32767.

    You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

  • SMTPSADD is the default SMTP server address for $SndMail. You can specify SMTPSADD as:
    • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
    • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
    • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

    You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

  • SMTPSPRT is the default SMTP server port for $SndMail. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of $SndMail.

Examples of running $SndMail

Example 1

%FROM = 'me@mydomain.com' %TO = 'My Friend <you@yourdomain.com>' %BNAME = 'mypicture.jpg' MODIFY BUFFER CLEAR IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY %ISIZE = $LOBLEN(SVRLOB) PRINT 'SIZE OF ' WITH %SVRKEY WITH ' IS ' WITH %ISIZE BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE END FOR PRINT 'BUFFER USED IS ' WITH $buffer_used %SUBJECT = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY %BODY = 'THIS BODY CONTAINS ' WITH %SVRKEY %RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,%BNAME)

In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. $SndMail sends this as a Base64-encoded attachment.

Note: The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.

Example 2

%TO ='JANE <YOU@YOURCORP.COM>' %BODY='See you at 9:30 AM tomorrow in the conference room' %RC =$SNDMAIL(,,%BODY,,%TO)

Example 3

The EMAILD argument is used to override the default domain names and ports.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTNAME = 'MYMVSSYSTEM' %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %S = 'EXAMPLE 1' /? SUBJECT LINE  ?/ %BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' %BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

Example 4

This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD SERVERDD IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional) CLIENTDD IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional) SERVERIPV6 IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional) CLIENTIPV6 IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional) END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01' %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %S = 'EXAMPLE 1' /? SUBJECT LINE ?/ %BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' %BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

ASCII translation

All text, except an optional binary attachment, is translated from EBCDIC to ASCII before sending.

Line ends

Text that is part of the header and body can include EBCDIC CRLF strings (X'0D25') that are translated to ASCII along with the rest of the text.

Reserved names

$SndMail uses Interface names CCAEM000 through CCAEM999. The user does not specify these names — the link name is generated by the function.

Socket limits

Up to 31 sockets are available on each link. If no more sockets are available on a particular link (CCAEM000, for example), the next link is tried. Thus, a maximum of 31,000 simultaneous email threads is theoretically possible.

Size of email message

The FROM, TO, CC, BCC, RCPTTO addresses, and body length, excluding the optional binary attachment, must total less than 27454 bytes.

Return code

$SndMail returns a fixed full word binary return code. See Handling error condition return codes for possible values.

RCPTTO parameter

If the $SndMail EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.

The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.

Using quotation marks

You must enclose the names of images within quotation marks, for example: 'BODY'. However, do not enclose the percent variable values within quotation marks, for example: %SUBJECT, not '%SUBJECT'.

Server and client names in the EMAILD parameters

In the EMAILD image, on a z/OS system, you can specify either or both the server and client names as domain names, for example: SMTPSERVER.YOURDOMAIN.COM or as an Internet Protocol (IP) address. If you specify the domain name, a TCP/IP call looks up the IP address.

  • If one field is present, all fields must be present, even if the optional fields are left blank.
  • If a name or port field is absent, it is taken from the CCAIN parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT.

The two port parameters have defaults: the SMTPSPRT default is 25; the SMTPCPRT default is 7700.

The two address parameters, SMTPSADD and SMTPCADD, can be specified either as domain names of up to 255 bytes or as IP addresses. If the address begins with an alphabetic character (A to Z), it is automatically evaluated as a domain name.

The four CCAIN default parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT can be examined using VIEW and changed using RESET.

References

For more information about the standards used in this function, please refer to these Internet Request for Comments documents:

  • RFC822, Standard for the format of ARPA Internet Text Messages
  • RFC2821, Simple Mail Transfer Protocol
  • RFC3548, The Base16, Base32, and Base64 Data Encoding

Error codes for $SndMail

$SndMail issues a return code. An error in $SndMail gives a return code of -1, and it is $StatusD that contains the error code.

The negative error codes starting with -999 are listed in Handling error condition return codes.

It is also possible that $SndMail will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.

However, in the case of a non-zero (error) return code, the following message is issued to the user:

M204.2799: $SndMail error errortext

When an attempt is made to set or reset the SMTPCADD or SMTPSADD parameters and the address translation fails, Model 204 issues the following messages:

RESET SMTPCADD CCAGGGG *** M204.2834: ADDRESS LOOKUP FAILED FOR CCAGGGG *** 1 M204.1123: PARAMETER SMTPCADD NOT RESET

Handling error condition return codes

Handling error condition return codes lists the possible $SOCKET return codes.

$Socket return codes
SMTP Error text Numeric value Meaning
ERBADARG -999 BAD ARGUMENT
ERNOTOPN -998 NOT OPEN
ERNOSTOR -997 NO STORAGE
ERIMAGER -996 IMAGE FAILURE
ERBADLNK -995 BAD LINK
ERNOTREL -994 SOCD NOT RELEASED
ERPHYERR -993 LINK DEAD
ERNOLINK -992 LINK UNKNOWN
ERTRUNC -991 VARIABLE TRUNCATION (READ CALL)
ERNOSOCK -990 SOCKET NOT FOUND
ERTRUNC2 -989 TRUNCATION ERROR ON IMAGE
EROPSYS -988 FUNCTION UNSUPPORTED ON THIS OPSYS
  -987 Not used
ERNOSRCD -986 NO SRCD
ERFDSLIM -985 TOO MANY SOCKETS
ERBADUBN -984 UNIVERSAL BUFFER NOT THERE
ERBADUBL -983 UNIVERSAL BUFFER LENGTH ERROR
ERBADUBA -982 UNIVERSAL BUFFER ALLOCATION ERROR
EREMREAD -981 ERROR WITH EMAIL SERVER READ
EREMWRIT -980 ERROR WITH EMAIL SERVER WRITE
ERGHBERR -979 SKIP=0 ERROR ON GETHOST CALL
ERGHERR1 -978 T1 LT 0 ERROR ON GETHOST CALL
ERGHERR2 -977 NO ADDRESSES RETURNED

When an error message (with code 5xx) is returned from the SMTP server, the following error message is displayed:

M204.2796: 'SMTP %C'

where %C is the error message returned by SMTP.

For the other error codes above, the following error message is returned, in addition to $StatusD being set.

M204.2799: '$SndMail error errorText'

where %C is listed in the following table:

Error text message possibilities for M204.2799
%C in message 2799 $StatusD code(s)
IN PARAMETER 999
- SOCKET NOT FOUND 990
- FUNCTION NOT SUPPORTED ON THIS SYSTEM 998
- NO SRCD 986
- TOO MANY SOCKETS 985
WITH UNIVERSAL BUFFER 984, 983, 982
Reading from SMTP server 981
Writing to SMTP server 980
Using GETHOSTBYNAME lookup 979, 978, 977
GETTING STORAGE 997
IN IMAGE PROCESSING 996
WITH TCP LINK 995, 998, 993, 992
- SOCD NOT RELEASED 994
READING DATA - TRUNCATION 991

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.

Note: It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.

Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.