https://m204wiki.rocketsoftware.com/api.php?action=feedcontributions&user=JAL&feedformat=atomm204wiki - User contributions [en]2024-03-28T16:30:04ZUser contributionsMediaWiki 1.40.1https://m204wiki.rocketsoftware.com/index.php?title=SOUL_$functions&diff=116992SOUL $functions2018-09-27T16:25:03Z<p>JAL: added (manually) a row for $JpStatL</p>
<hr />
<div>Some operations are inefficient or impossible to code in a high-level programming language like <var class="product">SOUL</var>. To overcome this difficulty, <var class="product">SOUL</var> provides a variety of $functions. Many of these functions are deprecated in favor of an OO API method. When that is the case, the $function page notes the matching method.<br />
<br />
<div id="otherLists"></div> <br />
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:<br />
<div class="showVisit"><br />
<table class="wikitable"><br />
<tr class="head"><th>$Function set</th><th>Description</th></tr><br />
<!-- Note: Rest of this table in synch with list in $Functions section of M204wiki contents --><br />
<tr><td>[[List of mathematical $functions|$xxxmath]]</td><td>Mathematical $functions</td></tr><br />
<tr><td>[[SirFact $functions|$Fact_xxx]]</td><td>SirFact $functions</td></tr><br />
<tr><td>[[List of Janus FTP Server $functions|$Ftp_xxx]]</td><td>Janus FTP Server $functions</td></tr><br />
<tr><td>[[List of Janus Sockets $functions|$Sock_xxx]]</td><td>Janus Sockets $functions</td></tr><br />
<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>Janus Web Server $functions</td></tr><br />
<tr><td>[[List of Sir2000 User Language Tools $functions|Sir2000]]</td><td>Sir2000 User Language Tools $functions</td></tr><br />
<!--<tr><td>[[List of OCM BOCES $functions]]</td><td>To support SIS</td></tr>--><br />
</table><br />
</div><br />
<br />
==List of standard $functions==<br />
The following table lists available <var class="product">SOUL</var> $functions, in alphabetical order. The list is not exhaustive (see the [[#otherLists|table of other $function sets]], above). <br />
<br />
<p class="note"><b>Note:</b> Some of the $functions listed below are only available with the purchase of a Model&nbsp;204 add-on product. The individual page containing such a $function's full description has an itemized list of the add-on products that authorize the use of the $function.</p><br />
<p><br />
See also: </p><br />
<ul><br />
<li>[[#Using_functions|Using functions]], which reviews coding in <var class="product">SOUL</var> with $functions </li><br />
<br />
<li>[[Notation conventions]], which provides a description of the conventions used in syntax on individual $function pages. </li><br />
</ul><br />
<br />
<div class="showVisit"><br />
<table class="wikitable"><br />
<tr class="head"><th>$Function</th><th>Description</th></tr><br />
<!-- ************************************************************** --><br />
<!-- Note that FUNSCHECK.WIKI depends on the format of the function name/description rows - *** SO DON'T MUCK WITH IT!!! *** --><br />
<!-- ************************************************************** --><br />
<tr><td>[[$Abbrev]]</td><td>Determine if string is abbreviation within list of words</td></tr><br />
<tr><td>[[$Account]]</td><td>Account under which the user is logged in.</td></tr><br />
<tr><td>[[$Acct]]</td><td>User ID under which the user is logged in.</td></tr><br />
<tr><td>[[$Alpha]]</td><td>Whether a string is composed of only the letters A through Z.</td></tr><br />
<tr><td>[[$AlphNum]]</td><td>Whether a string is composed of only the letters A through Z and digits 0 through 9.</td></tr><br />
<tr><td>[[$Arr_Find]]</td><td>Find value within array</td></tr><br />
<tr><td>[[$Arr_Init]]</td><td>Initialize every element of array to specific value</td></tr><br />
<tr><td>[[$Arr_Max]]</td><td>Find maximum value in array</td></tr><br />
<tr><td>[[$Arr_Min]]</td><td>Find minimum value in array</td></tr><br />
<tr><td>[[$ArrSize]]</td><td>Number of elements in a particular dimension of an array.</td></tr><br />
<tr><td>[[$Ascii]]</td><td>Input string, converted from EBCDIC to ASCII.</td></tr><br />
<tr><td>[[$A2E]]</td><td>Translate ASCII to EBCDIC</td></tr><br />
<tr><td>[[$Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr><br />
<tr><td>[[$Base64_Encode]]</td><td>Convert byte string to base 64</td></tr><br />
<tr><td>[[$BgPurge]]</td><td>Cancel "long" sdaemon request initiated with $CommBg</td></tr><br />
<tr><td>[[$BgQuery]]</td><td>List of "long" sdaemon requests initiated via $CommBg</td></tr><br />
<tr><td>[[$Binary]]</td><td>A number converted into fixed-point binary.</td></tr><br />
<tr><td>[[$Bind_List]]</td><td>Return list of bound semaphores onto a $list</td></tr><br />
<tr><td>[[$Bind]]</td><td>Fast, easy synchronization of system wide resource</td></tr><br />
<tr><td>[[$BitAnd]]</td><td>Bitwise AND of two integers</td></tr><br />
<tr><td>[[$BitOr]]</td><td>Bitwise OR of two integers</td></tr><br />
<tr><td>[[$BldProc]]</td><td>Enables a request to build a temporary procedure.</td></tr><br />
<tr><td>[[$Buffer_Position]]</td><td>Current Universal Buffer position.</td></tr><br />
<tr><td>[[$Buffer_Size]]</td><td>Size of user's Universal Buffer.</td></tr><br />
<tr><td>[[$Buffer_Used]]</td><td>Amount of data currently in Universal Buffer</td></tr><br />
<tr><td>[[$Bump]]</td><td>Bump a user</td></tr><br />
<tr><td>[[$CenqCt]]</td><td>Number of unused entries within the resource enqueuing table.</td></tr><br />
<tr><td>[[$Center]]</td><td>Center string</td></tr><br />
<tr><td>[[$CfStatL]]</td><td>List of statistics for users holding critical file resources</td></tr><br />
<tr><td>[[$ChkMod]]</td><td>Whether the terminal operator entered data in any full-screen input field.</td></tr><br />
<tr><td>[[$ChkPat]]</td><td>Syntax of a pattern.</td></tr><br />
<tr><td>[[$ChkpInf]]</td><td>Information about checkpoints</td></tr><br />
<tr><td>[[$ChkTag]]</td><td>Whether any erroneous full-screen input has been entered by the end user.</td></tr><br />
<tr><td>[[$Close]]</td><td>Close file or group in User Language request</td></tr><br />
<tr><td>[[$Cms]]</td><td>Determine if online is running under CMS</td></tr><br />
<tr><td>[[$Code]]</td><td>Encoding facility.</td></tr><br />
<tr><td>[[$Command]]</td><td>Execute Model 204 command on sdaemon, results to image</td></tr><br />
<tr><td>[[$CommBg]]</td><td>Execute Model 204 commands on sdaemon</td></tr><br />
<tr><td>[[$CommndL]]</td><td>Execute Model 204 command on sdaemon, results to $list</td></tr><br />
<tr><td>[[$Context]]</td><td>Determine if string is name of open file or group</td></tr><br />
<tr><td>[[$Curfile]]</td><td>Name of the file from which the current record has been selected.</td></tr><br />
<tr><td>[[$Currec]]</td><td>Integer equal to the internal number of the current record.</td></tr><br />
<tr><td>[[$C2D]]</td><td>Convert binary byte string to integer</td></tr><br />
<tr><td>[[$C2X]]</td><td>A translation of each byte within a character string to its two-byte hexadecimal representation.</td></tr><br />
<tr><td>[[$DaemonMasterNumber]]</td><td>Get user number of master thread</td></tr><br />
<tr><td>[[$DaemonParentNumber]]</td><td>Get user number of parent thread</td></tr><br />
<tr><td><div id="datex"></div>[[$Date]]</td><td>Current date in yy-mm-dd format.</td></tr><br />
<tr><td>[[$DateChg]]</td><td>Specified number of days, added to or subtracted from a given date.</td></tr><br />
<tr><td>[[$DateChk]]</td><td>Whether a given date is valid.</td></tr><br />
<tr><td>[[$DateCnv]]</td><td>Date converted to a format specified by the user.</td></tr><br />
<tr><td>[[$DateDif]]</td><td>Difference in days between two dates.</td></tr><br />
<tr><td>[[$DateP]]</td><td>Current date in "dd mon yy" format.</td></tr><br />
<tr><td>[[$DAY]]</td><td>Day name of the input day-number.</td></tr><br />
<tr><td>[[$DayI]]</td><td>Number reflecting current day of the week.</td></tr><br />
<tr><td>[[$Deblank]]</td><td>Substring of a string, with leading and trailing blanks removed.</td></tr><br />
<tr><td>[[$Decode]]</td><td>Decoding facility.</td></tr><br />
<tr><td>[[$Deflate]]</td><td>Compress a longstring with Deflate</td></tr><br />
<tr><td>[[$DelCh]]</td><td>Remove characters from string, compress and strip blanks</td></tr><br />
<tr><td>[[$Delg_Subsys]]</td><td>Delete subsystem-wide global</td></tr><br />
<tr><td>[[$Delg_Sys]]</td><td>Delete system-wide global</td></tr><br />
<tr><td>[[$Delimr]]</td><td>Insert delimiter string into input string at regular positions</td></tr><br />
<tr><td>[[$Dscr]]</td><td>Decoding facility.</td></tr><br />
<tr><td>[[$Dsn]]</td><td>Data set name when you specify a file's DD name and the ordinal number.</td></tr><br />
<tr><td>[[$DsnNum]]</td><td>Total number of data sets defined for a file when you specify the file's DD name.</td></tr><br />
<tr><td>[[$D2C]]</td><td>Binary byte representation of integer</td></tr><br />
<tr><td>[[$D2X]]</td><td>Hex representation of integer</td></tr><br />
<tr><td>[[$Ebcdic]]</td><td>Convert input string from ASCII to EBCDIC</td></tr><br />
<tr><td>[[$EcbDGet]]</td><td>Get string data associated with an Event Control Block (ECB)</td></tr><br />
<tr><td>[[$EcbDSet]]</td><td>Set string data associated with an Event Control Block (ECB)</td></tr><br />
<tr><td>[[$EcbTest]]</td><td>Check an Event Control Block (ECB) to see if it is posted</td></tr><br />
<tr><td>[[$EcfStat]]</td><td>Returns the detailed completion code from the previous EXTERNAL statement.</td></tr><br />
<tr><td>[[$Edit]]</td><td>Edited numeric and alphanumeric text</td></tr><br />
<tr><td>[[$EdScan]]</td><td>Scan list of entities in online</td></tr><br />
<tr><td>[[$Eformat]]</td><td>Exponent notations from converted numeric values</td></tr><br />
<tr><td>[[$Encrypt]]</td><td>A one-way encryption of a character string.</td></tr><br />
<tr><td>[[$Ent_Print]]</td><td>Set automatic character entity substitution</td></tr><br />
<tr><td>[[$Ent_Tab]]</td><td>retrieve/modify character entity substitution table</td></tr><br />
<tr><td>[[$Ent]]</td><td>Do character entity substitution</td></tr><br />
<tr><td>[[$Enter]]</td><td>Efficient terminal dialogue with users of data entry applications.</td></tr><br />
<tr><td>[[$ErrClr]]</td><td>Clears the error message text returned by the $Errmsg and $Fsterr functions.</td></tr><br />
<tr><td>[[$Errmsg]]</td><td>Prefix and text of the last counting error or request cancellation message received.</td></tr><br />
<tr><td>[[$ErrSet]]</td><td>Increment or clear number of counting errors, set $Errmsg</td></tr><br />
<tr><td>[[$E2A]]</td><td>Translate EBCDIC to ASCII</td></tr><br />
<tr><td>[[$FakeEnt]]</td><td>Prepare fake ENTER to automatically satisfy next full screen read</td></tr><br />
<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><br />
<tr><td>[[$Field_Image]]</td><td>Return field values into an image</td></tr><br />
<tr><td>[[$Field_List]]</td><td>Return field values into a $list</td></tr><br />
<tr><td>[[$Field_ListI]]</td><td>Return field values into a $list mapped to an image</td></tr><br />
<tr><td>[[$FieldgroupId]]</td><td>The ID of the current field group. (Available as of Model 204 version 7.5.)</td></tr><br />
<tr><td>[[$FieldgroupOccurrence]]</td><td>The current occurrence number of the field group. (Available as of Model 204 version 7.5.)</td></tr><br />
<tr><td>[[$FIniTim]]</td><td>File initialization YYDDDMMHHSSTH</td></tr><br />
<tr><td>[[$FiStat]]</td><td>Retrieve file's statistics into string</td></tr><br />
<tr><td>[[$FiStatL]]</td><td>Retrieve set of files' statistics into list</td></tr><br />
<tr><td>[[$FldLen]]</td><td>Length of a field.</td></tr><br />
<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><br />
<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><br />
<tr><td>[[$FlsAcc]]</td><td>User's access rights to a particular field.</td></tr><br />
<tr><td>[[$FlsChk]]</td><td>Whether a given set of field level security accesses is valid for a field.</td></tr><br />
<tr><td>[[$FreeOpt]]</td><td>Free optional file or group from subsystem</td></tr><br />
<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><br />
<tr><td>[[$FunForc]]</td><td>Cancel running or waiting Fast/Unload request</td></tr><br />
<tr><td>[[$FunImg]]</td><td>Retrieve data from active Fast/Unload request into image</td></tr><br />
<tr><td>[[$FunList]]</td><td>$list of active and enqueued Fast/Unload requests</td></tr><br />
<tr><td>[[$FunLoad]]</td><td>Fast/Unload records in Model 204 list or found set</td></tr><br />
<tr><td>[[$FunPurg]]</td><td>Purge running or waiting Fast/Unload request</td></tr><br />
<tr><td>[[$FunSkip]]</td><td>Skip to next output record for $FunImg, $FunsStr</td></tr><br />
<tr><td>[[$FunsStr]]</td><td>Retrieve data from active Fast/Unload request into string</td></tr><br />
<tr><td>[[$FunWait]]</td><td>Wait until asynchronous Fast/Unload request completes</td></tr><br />
<tr><td>[[$Getg]]</td><td>Information stored by a $SETG function.</td></tr><br />
<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><br />
<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><br />
<tr><td>[[$GrmLoc]]</td><td>Location of a missing member.</td></tr><br />
<tr><td>[[$GrmName]]</td><td>File name of a missing member.</td></tr><br />
<tr><td>[[$GrnLeft]]</td><td>Number of optional files that may fail before MAXFAIL is exceeded.</td></tr><br />
<tr><td>[[$GrnMiss]]</td><td>Number of missing members.</td></tr><br />
<tr><td>[[$GunZip]]</td><td>Decompress a longstring with GUNZIP</td></tr><br />
<tr><td>[[$GZip]]</td><td>Compress a longstring with GZip</td></tr><br />
<tr><td>[[$HexA]]</td><td>Convert hexadecimal string to EBCDIC equivalent</td></tr><br />
<tr><td>[[$HPage]]</td><td>String of special characters whose length is equal to the value specified as the $HPage argument.</td></tr><br />
<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><br />
<tr><td>[[$IHexA]]</td><td>Convert EBCDIC string to hexadecimal equivalent</td></tr><br />
<tr><td>[[$ImgInf]]</td><td>Retrieve image item by variable name</td></tr><br />
<tr><td>[[$ImgOvl]]</td><td>Replace image item value</td></tr><br />
<tr><td>[[$Incrg]]</td><td>Performs simple arithmetic on global variables.</td></tr><br />
<tr><td>[[$IncStat]]</td><td>Increment local system statistic</td></tr><br />
<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><br />
<tr><td>[[$Inflate]]</td><td>Decompress a longstring with inflate</td></tr><br />
<tr><td>[[$ItsOpen]]</td><td>Whether or not a file is open.</td></tr><br />
<tr><td>[[$ItsRemote]]</td><td>Whether the current file or group is remote or scattered.</td></tr><br />
<tr><td>[[$JobAuth]]</td><td>Determine if user has authorization for USE $JOB</td></tr><br />
<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><br />
<tr><td>[[$JpStat]]</td><td>Retrieve Janus port's statistics into string</td></tr><br />
<tr><td>[[$JpStatL]]</td><td>Retrieve statistics for set of Janus pors into $list</td></tr><br />
<tr><td>[[$LangSpc]]</td><td>String containing the binary value of a character in a specified language.</td></tr><br />
<tr><td>[[$LangSrt]]</td><td>A binary string translated to sort according to the NLSORT macro for the specified language.</td></tr><br />
<tr><td>[[$LangUst]]</td><td>Previously $LangSrt'ed string translated back to its original form.</td></tr><br />
<tr><td>[[$Len]]</td><td>Length of a value in a field.</td></tr><br />
<tr><td>[[$List_Add_Ordered]]</td><td>Add an item to an ordered $list</td></tr><br />
<tr><td>[[$List_Add_Unique_Ordered]]</td><td>Conditionally add an item to an ordered $list</td></tr><br />
<tr><td>[[$List_Add_Unique]]</td><td>Conditionally add an item to a $list</td></tr><br />
<tr><td>[[$List_Capture]]</td><td>Capture print data to $list</td></tr><br />
<tr><td>[[$List_Conv_Item]]</td><td>Convert $list to single delimited $list item</td></tr><br />
<tr><td>[[$List_Copy_Items]]</td><td>Copy items between $lists</td></tr><br />
<tr><td>[[$List_Diff_Item]]</td><td>Differences between $list and delimited $list item</td></tr><br />
<tr><td>[[$List_Global and $List_Session]]</td><td>Access/create global/session $list</td></tr><br />
<tr><td>[[$List_Global_Del and $List_Session_Del]]</td><td>Delete global/session $lists</td></tr><br />
<tr><td>[[$List_Global_List and $List_Session_List]]</td><td>List global/session $lists</td></tr><br />
<tr><td>[[$List_MaxIL]]</td><td>Return maximum $list item length</td></tr><br />
<tr><td>[[$List_Print]]</td><td>Display contents of a $list</td></tr><br />
<tr><td>[[$ListAdd_Lstr]]</td><td>Add longstring as new $list item</td></tr><br />
<tr><td>[[$ListAdd]]</td><td>Add string as new $list item</td></tr><br />
<tr><td>[[$ListAddI]]</td><td>Add image as new $list item</td></tr><br />
<tr><td>[[$ListAdj]]</td><td>Adjust length of $list item</td></tr><br />
<tr><td>[[$ListChk]]</td><td>Validate a $list identifier</td></tr><br />
<tr><td>[[$ListCmp]]</td><td>Compare two $lists and produce $list describing differences</td></tr><br />
<tr><td>[[$ListCnt]]</td><td>Number of items in $list</td></tr><br />
<tr><td>[[$ListCpy]]</td><td>Copy $list</td></tr><br />
<tr><td>[[$ListDel]]</td><td>Release CCATEMP storage used for $list</td></tr><br />
<tr><td>[[$ListFind]]</td><td>Find string in $list</td></tr><br />
<tr><td>[[$ListFindI and $ListFindI_Up]]</td><td>Find image item in $list</td></tr><br />
<tr><td>[[$ListFindI_Sub]]</td><td>Build $list subset based on image item</td></tr><br />
<tr><td>[[$ListILn]]</td><td>Length of $list item</td></tr><br />
<tr><td>[[$Listimg_Copy]]</td><td>Copy a $list's image association</td></tr><br />
<tr><td>[[$ListImg]]</td><td>Associate an image with a $list</td></tr><br />
<tr><td>[[$ListInf_Lstr]]</td><td>Retrieve $list item into longstring</td></tr><br />
<tr><td>[[$ListInf]]</td><td>Retrieve $list item into string</td></tr><br />
<tr><td>[[$ListInfI]]</td><td>Retrieve $list item into image</td></tr><br />
<tr><td>[[$ListIns_Lstr]]</td><td>Insert string into a $list</td></tr><br />
<tr><td>[[$ListIns]]</td><td>Insert string into a $list</td></tr><br />
<tr><td>[[$ListInsI]]</td><td>Insert image into a $list</td></tr><br />
<tr><td>[[$ListLoc]]</td><td>Locate string in $list</td></tr><br />
<tr><td>[[$ListLup]]</td><td>Locate string in $list, searching backwards</td></tr><br />
<tr><td>[[$ListMove]]</td><td>Move a $list</td></tr><br />
<tr><td>[[$ListNew]]</td><td>Create empty $list</td></tr><br />
<tr><td>[[$ListNewA]]</td><td>Create array of empty $lists</td></tr><br />
<tr><td>[[$ListNewAI]]</td><td>Create array of empty $lists associated with image</td></tr><br />
<tr><td>[[$ListNewI]]</td><td>Create empty $list associated with image</td></tr><br />
<tr><td>[[$ListOvl]]</td><td>Overlay part of $list item with string</td></tr><br />
<tr><td>[[$ListOvlI]]</td><td>Overlay part of $list item with image item</td></tr><br />
<tr><td>[[$ListRem]]</td><td>Remove item from $list</td></tr><br />
<tr><td>[[$ListRep_Lstr]]</td><td>Replace a $list item with a longstring</td></tr><br />
<tr><td>[[$ListRep]]</td><td>Replace a $list item with a string</td></tr><br />
<tr><td>[[$ListRepI]]</td><td>Replace $list item with an image</td></tr><br />
<tr><td>[[$ListRst]]</td><td>Restore global $list</td></tr><br />
<tr><td>[[$ListSav and $ListSave]]</td><td>Save global $list</td></tr><br />
<tr><td>[[$ListSavL]]</td><td>Count and names of available global $lists</td></tr><br />
<tr><td>[[$ListSort and $ListSrt]]</td><td>Sort $list</td></tr><br />
<tr><td>[[$ListSub]]</td><td>Create $list that is subset of input $list</td></tr><br />
<tr><td>[[$ListUpd]]</td><td>Produce $list from input $list using $list of updates</td></tr><br />
<tr><td>[[$Lowcase]]</td><td>A lower case string translated from an uppercase or mixed case string</td></tr><br />
<tr><td>[[$LstFld]]</td><td>Field names in a file, along with their field descriptions, into an image.</td></tr><br />
<tr><td>[[$LstProc]]</td><td>Information that is stored for a procedure.</td></tr><br />
<tr><td>[[$Lstr_Add_UserBuffer]]</td><td>Add longstring to user buffer</td></tr><br />
<tr><td>[[$Lstr_Base64_Decode]]</td><td>Convert from base 64 to byte string</td></tr><br />
<tr><td>[[$Lstr_Base64_Encode]]</td><td>Convert byte string to base 64</td></tr><br />
<tr><td>[[$Lstr_C2X]]</td><td>Convert byte string to hexadecimal</td></tr><br />
<tr><td>[[$Lstr_Get_Image and $Lstr_Set_Image]]</td><td>Longstring to/from image</td></tr><br />
<tr><td>[[$Lstr_Get_Userbuffer]]</td><td>Get user buffer contents to a longstring</td></tr><br />
<tr><td>[[$Lstr_Global and $Lstr_Session]]</td><td>Bind to global/session longstring</td></tr><br />
<tr><td>[[$Lstr_Global_Del and $Lstr_Session_Del]]</td><td>Delete global or session longstring</td></tr><br />
<tr><td>[[$Lstr_Global_Get and $Lstr_Session_Get]]</td><td>Get global or session longstring</td></tr><br />
<tr><td>[[$Lstr_Global_Set and $Lstr_Session_Set]]</td><td>Set global or session longstring</td></tr><br />
<tr><td>[[$Lstr_Index]]</td><td>Find a string inside a longstring</td></tr><br />
<tr><td>[[$Lstr_Left]]</td><td>Leftmost characters of a longstring</td></tr><br />
<tr><td>[[$Lstr_Len]]</td><td>Length of a longstring</td></tr><br />
<tr><td>[[$Lstr_Parse]]</td><td>Part of longstring preceding character in delimiter set</td></tr><br />
<tr><td>[[$Lstr_ParseX]]</td><td>Part of longstring following character in delimiter set</td></tr><br />
<tr><td>[[$Lstr_Right]]</td><td>Rightmost characters of a longstring</td></tr><br />
<tr><td>[[$Lstr_Set_UserBuffer]]</td><td>Set user buffer to longstring value</td></tr><br />
<tr><td>[[$Lstr_Substr]]</td><td>Substring of a longstring</td></tr><br />
<tr><td>[[$Lstr_SubWord]]</td><td>Substring of a longstring using word counts</td></tr><br />
<tr><td>[[$Lstr_Translate]]</td><td>Translate longstring</td></tr><br />
<tr><td>[[$Lstr_Unblank]]</td><td>Remove extraneous blanks from longstring</td></tr><br />
<tr><td>[[$Lstr_Windex]]</td><td>Return the position of a word within a long string</td></tr><br />
<tr><td>[[$Lstr_Word]]</td><td>Return a word from a long string</td></tr><br />
<tr><td>[[$Lstr_Words]]</td><td>Return the number of words in a long string</td></tr><br />
<tr><td>[[$Lstr_X2C]]</td><td>Convert from hexadecimal to byte string</td></tr><br />
<tr><td>[[$Lstr]]</td><td>Treat a string as longstring</td></tr><br />
<tr><td>[[$MisGrup]]</td><td>Group name if the error occurred in group context, null if in file context.</td></tr><br />
<tr><td>[[$MisLoc]]</td><td>Location of a missing member or file.</td></tr><br />
<tr><td>[[$MisName]]</td><td>File name of a missing member or file.</td></tr><br />
<tr><td>[[$MisNum]]</td><td>Number of files that failed in a group.</td></tr><br />
<tr><td>[[$MisStmt]]</td><td>Statement that caused the ON unit to be entered.</td></tr><br />
<tr><td>[[$Mod]]</td><td>Remainder that results when one argument is divided by the another argument.</td></tr><br />
<tr><td>[[$Occurs]]</td><td>Whether a field has the OCCURS attribute.</td></tr><br />
<tr><td>[[$Oneof]]</td><td>Table lookup that can replace a series of IF conditions.</td></tr><br />
<tr><td>[[$Pack]]</td><td>Packed decimal representation of a string.</td></tr><br />
<tr><td>[[$Pad]]</td><td>Designated character padded to the left.</td></tr><br />
<tr><td>[[$PadR]]</td><td>Designated character padded to the right</td></tr><br />
<tr><td>[[$Parse]]</td><td>Part of string preceding character in delimiter set</td></tr><br />
<tr><td>[[$ParseX]]</td><td>Part of string following character in delimiter set</td></tr><br />
<tr><td>[[$Post]]</td><td>Indicates that an event has occurred; the thread waiting on an ECB can resume processing.</td></tr><br />
<tr><td>[[$PrcLEx]]</td><td>$list of information about procedures in file</td></tr><br />
<tr><td>[[$PrcLExG]]</td><td>$list of information about procedures in group or file</td></tr><br />
<tr><td>[[$Priorty]]</td><td>Change a user's priority</td></tr><br />
<tr><td>[[$Proc_List]]</td><td>$list of information about procedures in file</td></tr><br />
<tr><td>[[$Proc_ListG]]</td><td>$list of information about procedures in group or file</td></tr><br />
<tr><td>[[$Proc_Touch]]</td><td>Change a procedure's last-update date and user</td></tr><br />
<tr><td>[[$ProcCls]]</td><td>Close procedure before reaching end</td></tr><br />
<tr><td>[[$ProcDat]]</td><td>Add lines from procedure to $list</td></tr><br />
<tr><td>[[$ProcGet]]</td><td>Next line of procedure</td></tr><br />
<tr><td>[[$ProcLoc]]</td><td>Locate any of set of strings in procedure</td></tr><br />
<tr><td>[[$ProcOpn]]</td><td>Open procedure for $ProcDat, $ProcGet, $ProcLoc</td></tr><br />
<tr><td>[[$Random_Seed]]</td><td>Build seed specifying series of $Random results</td></tr><br />
<tr><td>[[$Random]]</td><td>Get next random number</td></tr><br />
<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><br />
<tr><td>[[$Read]]</td><td>An echo of the data a user enters as a request is evaluated</td></tr><br />
<tr><td>[[$ReadInv]]</td><td>Performs the same function as $READ, except that input from the terminal is not echoed.</td></tr><br />
<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><br />
<tr><td>[[$RegexMatch]]</td><td>Whether string matches regex</td></tr><br />
<tr><td>[[$RegexReplace]]</td><td>Replace matching strings</td></tr><br />
<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><br />
<tr><td>[[$Resetn]]</td><td>Reset or view M204 parameter</td></tr><br />
<tr><td>[[$Reverse]]</td><td>Reversed order of a string.</td></tr><br />
<tr><td>[[$RlcFile]]</td><td>Name of the file in which the last record locking conflict occurred.</td></tr><br />
<tr><td>[[$RlcRec]]</td><td>Internal record number for which the last record locking conflict occurred.</td></tr><br />
<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><br />
<tr><td>[[$RlcUsr]]</td><td>User number of the user with which the request conflicted when the last record locking conflict occurred.</td></tr><br />
<tr><td>[[$Round]]</td><td>Number, rounded to a specified number of decimal places.</td></tr><br />
<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><br />
<tr><td>[[$Sclass]]</td><td>Current user's subsystem user class.</td></tr><br />
<tr><td>[[$Screen_attr]]</td><td>Get screen item attributes as a blank-delimited string</td></tr><br />
<tr><td>[[$Screen_clear]]</td><td>Clear tagged and/or modified attributes in a screen</td></tr><br />
<tr><td>[[$Screen_mod]]</td><td>Set modified attribute for a screen item</td></tr><br />
<tr><td>[[$ScrHide]]</td><td>Hide lines in SCREEN</td></tr><br />
<tr><td>[[$ScrSize]]</td><td>Change size of field on SCREEN</td></tr><br />
<tr><td>[[$ScrWide]]</td><td>Allow SCREEN to accept fields wider than 79</td></tr><br />
<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><br />
<tr><td>[[$Session_Close]]</td><td>Close an open session</td></tr><br />
<tr><td>[[$Session_Create]]</td><td>Create a new session</td></tr><br />
<tr><td>[[$Session_Delete]]</td><td>Delete a session</td></tr><br />
<tr><td>[[$Session_List]]</td><td>Get list of sessions</td></tr><br />
<tr><td>[[$Session_Open]]</td><td>Open a session</td></tr><br />
<tr><td>[[$Setg_Subsys_List]]</td><td>Get list of subsystem-wide globals</td></tr><br />
<tr><td>[[$Setg_Subsys]]</td><td>Set subsystem-wide global</td></tr><br />
<tr><td>[[$Setg_Sys_List]]</td><td>Get list of system-wide globals</td></tr><br />
<tr><td>[[$Setg_Sys]]</td><td>Set system-wide global</td></tr><br />
<tr><td>[[$Setg]]</td><td>A created or changed entry in the global variable section of GTBL.</td></tr><br />
<tr><td>[[$SetL]]</td><td>Sets the current line counter for the output device currently in effect.</td></tr><br />
<tr><td>[[$SetP]]</td><td>Sets the current page number for the output device currently in effect.</td></tr><br />
<tr><td>[[$SetStat]]</td><td>Set local system statistic</td></tr><br />
<tr><td><div id="datetime"></div>[[$Sir_Date]]</td><td>Get current datetime</td></tr><br />
<tr><td>[[$Sir_DateFmt]]</td><td>Validate datetime format</td></tr><br />
<tr><td><div id="daten"></div>[[$Sir_DateN]]</td><td>Current date and time as number of seconds/300</td></tr><br />
<tr><td>[[$Sir_DateND]]</td><td>Current date as number of days</td></tr><br />
<tr><td>[[$Sir_DateNM]]</td><td>Current date and time as number of milliseconds</td></tr><br />
<tr><td>[[$Sir_DateNS]]</td><td>Current date and time as number of seconds</td></tr><br />
<tr><td>[[$Sir_Date2N]]</td><td>Convert datetime string to number of seconds/300</td></tr><br />
<tr><td>[[$Sir_Date2ND]]</td><td>Convert datetime string to number of days</td></tr><br />
<tr><td>[[$Sir_Date2NM]]</td><td>Convert datetime string to number of milliseconds</td></tr><br />
<tr><td>[[$Sir_Date2NS]]</td><td>Convert datetime string to number of seconds</td></tr><br />
<tr><td>[[$Sir_Login]]</td><td>Perform secured web or sockets login</td></tr><br />
<tr><td>[[$Sir_ND2Date]]</td><td>Convert datetime number of days to string</td></tr><br />
<tr><td>[[$Sir_NM2Date]]</td><td>Convert datetime number of milliseconds to string</td></tr><br />
<tr><td>[[$Sir_NS2Date]]</td><td>Convert datetime number of seconds to string</td></tr><br />
<tr><td>[[$Sir_N2Date]]</td><td>Convert datetime number of seconds/300 to string</td></tr><br />
<tr><td>[[$Sir_Wild]]</td><td>Test string against a wildcard string</td></tr><br />
<tr><td>[[$SirJGet]]</td><td>Place audit trail data on $list</td></tr><br />
<tr><td>[[$SirMsg]]</td><td>Line of current $SirMsgP procedure</td></tr><br />
<tr><td>[[$SirMsgP]]</td><td>Load procedure for retrieval via $SirMsg</td></tr><br />
<tr><td>[[$SirParm]]</td><td>Set user-specific value, controlling Sirius products</td></tr><br />
<tr><td>[[$SirProd]]</td><td>Determine availability of Sirius product or capability</td></tr><br />
<tr><td>[[$SirSite]]</td><td>Current Sirius customer site ID</td></tr><br />
<tr><td>[[$SirTime]]</td><td>Current time as YYDDDHHMISSXX</td></tr><br />
<tr><td>[[$SirVer]]</td><td>Current version number of Sirius product</td></tr><br />
<tr><td>[[$SirWarn]]</td><td>Send warning or message to user(s)</td></tr><br />
<tr><td>[[$Slstats]]</td><td>Resets the recording of since-last statistics anywhere within a request.</td></tr><br />
<tr><td>[[$SndMail]]</td><td>Send an email message</td></tr><br />
<tr><td>[[$Sndx]]</td><td>SOUNDEX code of an argument.</td></tr><br />
<tr><td>[[$Square]]</td><td>A number multiplied by itself.</td></tr><br />
<tr><td>[[$SsStat]]</td><td>Retrieve subsystem's statistics into string</td></tr><br />
<tr><td>[[$SsStatL]]</td><td>Retrieve statistics for set of subsystems into $list</td></tr><br />
<tr><td>[[$Stat]]</td><td>Current value of any user statistic.</td></tr><br />
<tr><td>[[$StatD]]</td><td>Calculate differences and rates for statistics strings</td></tr><br />
<tr><td>[[$StatLD]]</td><td>Calculate differences and rates for statistics $lists</td></tr><br />
<tr><td>[[$Status]]</td><td>The success or failure of the last executed external I/O or program communication statement.</td></tr><br />
<tr><td>[[$StatusD]]</td><td>More detailed description of a condition returned by $STATUS.</td></tr><br />
<tr><td>[[$Str]]</td><td>Treat a longstring as string</td></tr><br />
<tr><td>[[$StrAnd]]</td><td>Bit-wise AND two strings</td></tr><br />
<tr><td>[[$Strip]]</td><td>A number with suppressed leading zeros.</td></tr><br />
<tr><td>[[$StrOr]]</td><td>Bit-wise OR two strings</td></tr><br />
<tr><td>[[$StrXor]]</td><td>Bit-wise exclusive OR two strings</td></tr><br />
<tr><td>[[$SubCnt]]</td><td>Count occurrences of one string in another</td></tr><br />
<tr><td>[[$SubErs]]</td><td>Remove occurrence of one string from another</td></tr><br />
<tr><td>[[$SubIns]]</td><td>Insert string inside another string</td></tr><br />
<tr><td>[[$SubRep]]</td><td>Replace occurrences of string</td></tr><br />
<tr><td>[[$Substr]]</td><td>Substring of a string.</td></tr><br />
<tr><td>[[$Subsys]]</td><td>Status of an APSY subsystem.</td></tr><br />
<tr><td>[[$SyStat]]</td><td>Retrieve system statistics into string</td></tr><br />
<tr><td>[[$TableC]]</td><td>Information provided by TABLEC command</td></tr><br />
<tr><td>[[$TermId]]</td><td>Terminal ID of current user thread</td></tr><br />
<tr><td>[[$Time]]</td><td>Current time in hh:mm:ss format.</td></tr><br />
<tr><td>[[$TkStat]]</td><td>Retrieve task's statistics into string</td></tr><br />
<tr><td>[[$TkStatL]]</td><td>Retrieve statistics for all tasks into $list</td></tr><br />
<tr><td>[[$TsoAtt]]</td><td>Attach program in user's TSO address space</td></tr><br />
<tr><td>[[$TsoCall]]</td><td>Call program in user's TSO address space</td></tr><br />
<tr><td>[[$TsoCan]]</td><td>Cancel program invoked via $TsoAtt</td></tr><br />
<tr><td>[[$TsoCmd]]</td><td>Invoke command in user's TSO address space</td></tr><br />
<tr><td>[[$TsoExec]]</td><td>Invoke CLIST in user's TSO address space</td></tr><br />
<tr><td>[[$TsoExit]]</td><td>Terminate TSO full screen interface session, stack command</td></tr><br />
<tr><td>[[$TSOId]]</td><td>TSO userid user's thread</td></tr><br />
<tr><td>[[$TSOStat]]</td><td>Status of program invoked via $TsoAtt</td></tr><br />
<tr><td>[[$TSOWait]]</td><td>Wait for program invoked via $TsoAtt to complete</td></tr><br />
<tr><td>[[$Unbin]]</td><td>Value converted from binary to string representation.</td></tr><br />
<tr><td>[[$Unbind_and_$UnbindW]]</td><td>$Unbind and $UnbindW: Unbind resource previously bound via $Bind</td></tr><br />
<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><br />
<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><br />
<tr><td>[[$Unpack]]</td><td>Unpacked decimal data </td></tr><br />
<tr><td>[[$UnPost]]</td><td>Resets a specified Event Control Block (ECB) to an unposted state.</td></tr><br />
<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><br />
<tr><td>[[$UnSpace]]</td><td>Normalize spaces and quotes</td></tr><br />
<tr><td>[[$Upcase]]</td><td>An uppercase string converted from a lower or mixed case string.</td></tr><br />
<tr><td>[[$Update]]</td><td>Name of the group update file or the current file.</td></tr><br />
<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><br />
<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><br />
<tr><td>[[$UpdLoc]]</td><td>Location name (node name) of the current update unit (Parallel Query Option/204 only).</td></tr><br />
<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><br />
<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><br />
<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><br />
<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><br />
<tr><td>[[$UpdVal]]</td><td>Field value causing a field level constraint violation, or a blank if no violation occurred.</td></tr><br />
<tr><td>[[$UseASA]]</td><td>Prevent carriage control in USE output</td></tr><br />
<tr><td>[[$User]]</td><td>User's user number.</td></tr><br />
<tr><td>[[$Userid]]</td><td>User ID under which the user is logged in.</td></tr><br />
<tr><td>[[$UsrPriv]]</td><td>Whether a user ID has been granted specific <var class="product">Model&nbsp;204</var> privileges.</td></tr><br />
<tr><td>[[$UsStat]]</td><td>Retrieve user's statistics into string</td></tr><br />
<tr><td>[[$UsStatL]]</td><td>Retrieve statistics for set of users into $list</td></tr><br />
<tr><td>[[$Verify]]</td><td>Whether every character in one string is present in a second string.</td></tr><br />
<tr><td>[[$View]]</td><td>Value of a parameter.</td></tr><br />
<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><br />
<tr><td>[[$Wait]]</td><td>Suspend a user until an Event Control Block (ECB) is posted.</td></tr> <br />
<tr><td>[[$WakeUp]]</td><td>Pause user until specified time</td></tr><br />
<!--bypass FUNCHECK.WIKI--><br />
<tr><td>[[List of Janus Web Server $functions|$Web_xxx]]</td><td>List of Janus Web Server $functions</td></tr><br />
<tr><td>[[$Windex]]</td><td>Word number of first occurrence of word in phrase</td></tr><br />
<tr><td>[[$Word]]</td><td>P word in a specified string, delimited by a blank or optionally specified character.</td></tr><br />
<tr><td>[[$Words]]</td><td>Number of words in a specified string, delimited by a blank or optionally specified character.</td></tr><br />
<tr><td>[[$X2C]]</td><td>One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.</td></tr><br />
<tr><td>[[$X2D]]</td><td>Convert hex string to integer</td></tr><br />
</table><br />
</div><br />
<br />
==Using functions==<br />
You can use functions in several ways, including, as a term in:<br />
<ul><br />
<li>An expression in a variable assignment statement, for example:</li><br />
</ul><br />
<p class="code">%X=$EDIT(2573,'99999')<br />
</p><br />
<ul><br />
<li>The specifications in a PRINT statement</li><br />
</ul><br />
<p><br />
A PRINT statement can include a function call anywhere a field name can be used. For example:</p><br />
<p class="code">PRINT $EDIT(2573,'99999')<br />
</p><br />
<ul><br />
<li>An expression in a conditional statement, for example:</li><br />
</ul><br />
<p class="code">IF $EDIT(2573,'99999') EQ 02573 THEN...<br />
</p><br />
<ul><br />
<li>An expression which serves as the argument to another function, for example:</li><br />
</ul><br />
<p class="code">%L=$LEN($EDIT(2573,'99999'))<br />
</p><br />
<p><br />
The direct use of function calls in some statements, such as FIND, results in compilation errors. </p><br />
<br />
====Comparing successful and unsuccessful $function code====<br />
<p><br />
If your request is coded as follows:</p><br />
<p class="code">BEGIN<br />
$EDIT(2573,'99999')<br />
END<br />
</p><br />
<p><br />
The following error is your result:</p><br />
<p class="code"><b></b>*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')<br />
</p><br />
<p><br />
However, if you code your request as follows, it works properly:</p><br />
<p class="code">BEGIN<br />
PRINT $EDIT(2573,'99999')<br />
<b></b>* Or *<br />
<b></b>* %X=$EDIT(2573,'99999') *<br />
END<br />
</p><br />
<br />
===Function return values===<br />
<p><br />
Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:</p><br />
<p class="code">%a = $account<br />
</p><br />
<p><br />
This function causes the length of the current value of the FULLNAME field to be compared to 10:</p><br />
<p class="code">IF $LEN(FULLNAME) GT 10 THEN<br />
.<br />
.<br />
.<br />
</p><br />
<br />
===Function arguments===<br />
<p><br />
Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:</p><br />
<p class="code">IF $READ('CONTINUE?') EQ 'YES' THEN<br />
.<br />
.<br />
.<br />
%X = $mod(COUNT IN CT, %BASE)<br />
</p><br />
<br />
====Rules for function arguments====<br />
<p><br />
Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using variables and values in computation#Expressions|Expressions]] for detailed information on expression syntax.</p><br />
<br />
====Argument evaluation and conversion====<br />
<p><br />
<var class="product">Model&nbsp;204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:</p><br />
<ul><br />
<li>If an argument is expected to be numeric but is a string, <var class="product">Model&nbsp;204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using variables and values in computation#Relationship between %variable assignment and declaration|Relationship between %variable assignment and declaration]] and [[Using variables and values in computation#Conversion|Conversion]]. </li><br />
</li><br />
<li>If an argument is expected to be a string but is numeric, <var class="product">Model&nbsp;204</var> converts the number to a string. </li><br />
</li><br />
<li>If the original number contains decimal places, they are lost during the conversion.</li><br />
</li><br />
</ul><br />
<br />
==User-written functions==<br />
<p><br />
In addition to the functions provided by <var class="product">SOUL</var>, some customer sites write their own functions based on their particular needs.<br />
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><br />
<br />
<blockquote class="note"><br />
<b>Notes:</b><br />
<ul><br />
<li>It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.<br />
<li>The RESULT macro does not work in Model 204 Version 5.1 and later. Change any use of the RESULT macro in $functions to use the standard LEAVENUM, LEAVEF0 and LEAVESTR macros.<br />
<li>In addition to the above considerations, see the [[Model 204 installation#FUNU|installation instructions relating to FUNU]].<br />
</ul></blockquote><br />
<br />
<p>Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.</p><br />
<br />
[[Category:SOUL]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$JpStatL&diff=116957$JpStatL2018-09-20T23:38:40Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$JpStatL}}<br />
<span class="pageSubtitle">Retrieve statistics for set of Janus ports into $list</span><br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = <span class="literal">$JpStatL</span>(<span class="term">list_identifier</span>, <span class="term">stat_list</span>)<br />
</p><br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%result</th><br />
<td>Either a positive number, which is the milliseconds since the Online was brought up, or a negative [[#Error codes|error code]].</td></tr><br />
<br />
<tr><th>list_identifier</th><br />
<td>The identifier of the $list to receive the results. The current contents of the $list are deleted and replaced with the requested statistics. The format of each $list item is:<br />
<br />
<table><br />
<tr><td>Byte 1-30</td><br />
<td>Blank padded port name</td></tr><br />
<br />
<tr><td>Byte 31-32</td><br />
<td>Binary port number</td></tr><br />
<br />
<tr><td>Byte 33-</td><br />
<td>Returned statistics</td></tr><br />
</table><br />
</td></tr><br />
<br />
<tr><th>stat_list</th><br />
<td>A string of blank delimited words indicating the statistics to be returned. The length of each returned statistic is always a multiple of four bytes. This facilitates the use of <var>[[$StatLD]]</var> with the returned $list. For more information about available statistics, see [[SirMon Janus Monitor menu]]. </td></tr><br />
</table><br />
<br />
===Error codes===<br />
<p class="code"> -3 &mdash; CCATEMP is full.<br />
-5 &mdash; Required parameter not specified.<br />
-6 &mdash; Invalid $list identifier.<br />
-12 &mdash; Invalid parameter in <var class="term">stat_list</var>.<br />
-13 &mdash; STAT not linked in.<br />
-17 &mdash; No Janus port active.<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}==<br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$UsStatL]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$JpStatL&diff=116956$JpStatL2018-09-20T23:35:45Z<p>JAL: </p>
<hr />
<div><br />
<span class="pageSubtitle">Retrieve statistics for set of Janus ports into $list</span><br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = <span class="literal">$JpStatL</span>(<span class="term">list_identifier</span>, <span class="term">stat_list</span>)<br />
</p><br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%result</th><br />
<td>Either a positive number, which is the milliseconds since the Online was brought up, or a negative [[#Error codes|error code]].</td></tr><br />
<br />
<tr><th>list_identifier</th><br />
<td>The identifier of the $list to receive the results. The current contents of the $list are deleted and replaced with the requested statistics. The format of each $list item is:<br />
<br />
<table><br />
<tr><td>Byte 1-30</td><br />
<td>Blank padded port name</td></tr><br />
<br />
<tr><td>Byte 31-32</td><br />
<td>Binary port number</td></tr><br />
<br />
<tr><td>Byte 33-</td><br />
<td>Returned statistics</td></tr><br />
</table><br />
</td></tr><br />
<br />
<tr><th>stat_list</th><br />
<td>A string of blank delimited words indicating the statistics to be returned. The length of each returned statistic is always a multiple of four bytes. This facilitates the use of <var>[[$StatLD]]</var> with the returned $list. For more information about available statistics, see [[SirMon Janus Monitor menu]]. </td></tr><br />
</table><br />
<br />
===Error codes===<br />
<p class="code"> -3 &mdash; CCATEMP is full.<br />
-5 &mdash; Required parameter not specified.<br />
-6 &mdash; Invalid $list identifier.<br />
-12 &mdash; Invalid parameter in <var class="term">stat_list</var>.<br />
-13 &mdash; STAT not linked in.<br />
-17 &mdash; No Janus port active.<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}==<br />
<ul class="smallAndTightList"><br />
<li>[[List of $functions|Sirius functions]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$UsStatL]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$Proc_Touch&diff=116808$Proc Touch2018-09-20T22:36:06Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$Proc_Touch}}<br />
<span class="pageSubtitle">Change a procedure's last-update date and user</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Proc_Touch function.</p><br />
<br />
<var>$Proc_Touch</var> lets you change the last updating date/time, account ID, or both, of a <var class="product">Model 204</var> procedure. <br />
<br />
<var>$Proc_Touch</var> is a [[Calling Sirius Mods $functions|callable]] function that accepts four string arguments and returns a numeric completion code.<br />
<br />
==Syntax==<br />
<p class="syntax">[%result =] $Proc_Touch (filename, procname, datetime, id)<br />
</p><br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%result</th><br />
<td>Integer that indicates the success of the function.</td></tr><br />
<br />
<tr><th>filename</th><br />
<td>Name of file containing the procedure. If this argument is null, blank, or not specified, the current default file name is used. The file must be open.</td></tr><br />
<br />
<tr><th>procname</th><br />
<td>Name of the procedure to be "touched," that is, whose last-updating information is to be modified.</td></tr><br />
<br />
<tr><th>datetime</th><br />
<td>Date/time specification in either of the following formats: <var>YYDDDHHMISSXX</var> or <var>YYYYDDDHHMISSXX</var>. If <code>YY</code> is used, <var>[[Datetime string formats#Using CENTSPAN|CENTSPAN]]</var> is 1975. This argument may be a date and time in the future. If this argument is null or omitted, the current date and time is used. For more information about the CENTSPAN mechanism, </td></tr><br />
<br />
<tr><th>id</th><br />
<td>Account ID (ten-character maximum) to become the last updator. If <var class="term">id</var> is not supplied, is null, or is blank, the ID of the <var>$Proc_Touch</var> caller is used. <br />
<p><br />
'''Note: ''' This need not be the name of a valid user (this value is not validated, and it may include embedded blanks).</p></td></tr><br />
</table><br />
<br />
===Return codes===<br />
<p class="code">0 - Success<br />
1 - Procedure is in use<br />
2 - Procedure does not exist or is secured<br />
3 - Procedure name missing<br />
4 - File name invalid<br />
5 - No update privileges in file<br />
6 - Invalid touch time<br />
7 - Invalid account ID<br />
</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Besides its use internally by <var class="product">[[SirLib]]</var> to set more meaningful date/time stamps, <var>$Proc_Touch</var> is also useful for correcting the results of <var class="product">Model 204</var> <var>COPY PROC</var> commands (when the old date/time is lost because <code>OLDDATE</code> was not specified).<br />
<li>These restrictions apply to a <var>$Proc_Touch</var> operation:<br />
<ul><br />
<li>It must not be issued in the middle of another updating transaction. <br />
<li>It is not part of an update unit and cannot be backed out. <br />
<li>No roll-forward information is logged (or processed), so the effect of a <var>$Proc_Touch</var> could get lost if recovery is run.<br />
</ul><br />
</ul><br />
<br />
==Examples==<br />
In the following example, procedure COMP in file TESTPROC, last updated by user JACK, is "touched" to acquire an older date and user JACK3 as the last updating date and user:<br />
<p class="code"> Begin<br />
%RC is float<br />
OPEN FILE TESTPROC<br />
%RC = $Proc_Touch('TESTPROC', 'COMP', '200436411111111', 'JACK3')<br />
Print 'TOUCH return code is: ' %RC<br />
End<br />
</p><br />
<br />
After this request finishes, the result of a DISPLAY PROC LIST command shows the modified date of the request and user JACK3 for the last update for procedure COMP:<br />
<p class="code"> COMP 12/29/04 11:11:11 136 JACK3<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]<br />
<li>[[SirLib]]<br />
</ul><br />
<br />
[[Category:$Functions|$Proc_Touch]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$ProcDat&diff=116807$ProcDat2018-09-20T22:35:30Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$ProcDat}}<br />
<span class="pageSubtitle">Add lines from procedure to $list</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ProcDat function is <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var>.</p><br />
<br />
The <var>$ProcDat</var> function accepts three arguments, and returns a numeric code. <br />
<br />
The first argument identifies the $list to which lines from the currently open procedure will be added as $list items. This is a required argument. <br />
<br />
The second argument is an optional number of lines to be read. If the second argument is not provided, reading continues from the input procedure to the end of the procedure. <br />
<br />
The third argument specifies a sequence number increment for 8 byte sequence numbers to be placed in front of each line in the output $list. This sequence number indicates both the starting sequence number and the sequence number increment. If this parameter is not provided, no sequence numbers are placed in front of the input lines.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = $ProcDat ( list_identifier, num_lines, seq_inc )<br />
</p><br />
<br />
<p><br />
<var class="term">%result</var> is set to indicate the success of the function.</p><br />
<br />
The third argument to <var>$ProcDat</var> is intended for use in conjunction with the <var>[[$ListUpd]]</var> and <var>[[$ListCmp]]</var> functions. <br />
<br />
===Return codes===<br />
<p class="code">-1 - Current include level not opened by $ProcOpn<br />
-3 - No room to create $list items<br />
(if LISTFC <var>$SirParm</var> parameter not set)<br />
-5 - Required parameter missing<br />
-6 - Invalid $list identifier<br />
</p><br />
<br />
==Examples==<br />
If procedure 'SUTPENS_HUNDRED' in file 'JACKSON' contains:<br />
<p class="code">B<br />
FOR %I FROM 1 TO 10<br />
PRINT %I<br />
END FOR<br />
END<br />
</p><br />
<br />
This program:<br />
<br />
<p class="code">B<br />
%LIST = $ListNew<br />
<br />
%RESULT = $ProcOpn('SUTPENS_HUNDRED', 'JACKSON')<br />
%RESULT = $ProcDat(%LIST, ,5000)<br />
<br />
FOR %I FROM 1 TO $ListCnt(%LIST)<br />
PRINT $ListInf(%LIST, %I)<br />
END FOR<br />
END<br />
</p><br />
<br />
Prints the following:<br />
<br />
<p class="code">00005000B<br />
00010000FOR %I FROM 1 TO 10<br />
00015000 PRINT %I<br />
00020000END FOR<br />
00025000END<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]<br />
<li>[[Fast/Unload User Language Interface]]<br />
<li>[[Janus Web Server]]<br />
</ul><br />
<br />
[[Category:$Functions|$ProcDat]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$ProcCls&diff=116806$ProcCls2018-09-20T22:34:59Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$ProcCls}}<br />
<span class="pageSubtitle">Close procedure before reaching end</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is currently no OO equivalent for the $ProcCls function.</p><br />
<br />
The <var>$ProcCls</var> function may be used to "close" a procedure before reaching its end. <br />
<br />
The <var>$ProcCls</var> function accepts no arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = $ProcCls<br />
</p><br />
<br />
<p><br />
<var class="term">%result</var> is set to indicate the results of the function.</p><br />
<br />
===Return codes===<br />
<p class="code">-1 - Current include level not opened by $ProcOpn<br />
0 - Include level closed, no more <var>$ProcOpn</var> levels left<br />
N - Include level close, N <var>$ProcOpn</var> levels left<br />
</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li>If <var>$ProcCls</var> is called before the current procedure has been completely processed, the current procedure is closed and the next [[$ProcGet]], [[$ProcDat]], or [[$ProcLoc]] call operates on the previous procedure, if any. <var>$ProcCls</var> will not close an input stream that was not open via [[$ProcOpn]]. <br />
</ul><br />
<br />
==Example==<br />
The following instructions close all procedure input streams opened by $ProcOpn.<br />
<p class="code">REPEAT UNTIL %RESULT <= 0<br />
%RESULT = $ProcCls<br />
END REPEAT<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]<br />
<li>[[Fast/Unload User Language Interface]]<br />
<li>[[Janus Web Server]]<br />
</ul><br />
<br />
[[Category:$Functions|$ProcCls]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$ProcLoc&diff=116805$ProcLoc2018-09-20T22:34:18Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$ProcLoc}}<br />
<span class="pageSubtitle">Locate any of set of strings in procedure</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $ProcLoc is <var>[[Locate and LocateUp (Stringlist functions)|Locate]]</var>, if <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> is used to retrieve the procedure into a <var>Stringlist</var>.</p><br />
<br />
The <var>$ProcLoc</var> function accepts five arguments and returns a numeric result. <br />
<br />
The first four arguments identify strings to be located in the currently open procedure. If any of the specified strings is located in a given line of the procedure, the search is terminated. At least one search string must be specified. The total length of the first 4 arguments must be 256 or less. <br />
<br />
The fifth argument, if set to 'Y', indicates that the case of the data in a procedure line must match the case of the data in the search strings for a string to be considered "matched." If this argument is not set to 'Y', a lowercase character would be considered to match the corresponding uppercase character, and vice versa.<br />
<br />
The sixth argument, available in <var class="product">Sirius Mods</var> 8.1 and later, if set to 'Y', indicates that single (') and double (") quotes are to be considered as matches for each other. This can be useful when searching through procedures that contain code where single and double quotes can be used interchangeably to enclose string literals. Such code includes User Language, Javascript, and XML (including XSLT). <br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$ProcLoc</span>( {<span class="term">string1</span>, <span class="term">string2</span>, <span class="term">string3</span>, <span class="term">string4</span> }, [<span class="term">respect</span>], [<span class="term">arb_quote</span>])<br />
</p><br />
<br />
===Return codes===<br />
<p class="code">>0 - The number of lines that were tested before the<br />
string or strings were located<br />
-1 - Current include level not opened by $ProcOpn<br />
-2 - Search string or strings not found<br />
-3 - No search strings were specified<br />
-4 - Total length of search strings > 256<br />
</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li><var>$ProcLoc</var> positions the "current line" in the file so that a subsequent <var>[[$ProcGet]]</var> would return the line containing the matched string or strings. If you wish to continue searching through the current procedure for the next occurrence of a string or strings you must issue a <var>$ProcGet</var> to advance the current line. If you do not, <var>$ProcLoc</var> will continue to match on the current line. <br />
<p><br />
For example, the following code, displays the line number and contents of every line in procedure <code>BIGPROC</code> that contains either the string <code>REPEAT</code> or the string <code>ARRAY</code>: </p><br />
<br />
<p class="code">%A = $ProcOpn('BIGPROC')<br />
%LINE_NUM = 0<br />
%A = 1<br />
REPEAT WHILE %A GT 0<br />
%A = $ProcLoc('REPEAT','ARRAY')<br />
IF %A GT 0 THEN<br />
%LINE_NUM = %LINE_NUM + %A<br />
PRINT %LINE_NUM AND $ProcGet<br />
END IF<br />
END REPEAT<br />
</p><br />
</ul><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]<br />
<li>[[Fast/Unload User Language Interface]]<br />
<li>[[Janus Web Server]]<br />
</ul><br />
<br />
[[Category:$Functions|$ProcLoc]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$ProcGet&diff=116804$ProcGet2018-09-20T22:33:48Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$ProcGet}}<br />
<span class="pageSubtitle">Next line of procedure</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no direct OO equivalent for the $ProcGet function, however a whole family of methods is available, based on the OO interface to stringLists. See the <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> as a starting point.</p><br />
<br />
<var>$ProcGet</var> accepts no arguments and returns a string result. Each call to <var>$ProcGet</var> returns either the next line of the current procedure or a null string to signify the end of the current procedure. If the next input line from the current procedure contains a <code>??</code>, the <code>??</code> is replaced by the third argument specified on the <var>[[$ProcOpn]]</var> associated with the open procedure, just as if the third <var>$ProcOpn</var> argument had been specified after the procedure name on an <var>INCLUDE</var> command.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%x</span> = <span class="literal">$ProcGet</span>()<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li><var class="product">[[Sirius Functions]]</var> <br />
<li><var class="product">[[Fast/Unload User Language Interface]]</var><br />
<li><var class="product">[[Janus Web Server]]</var><br />
</ul><br />
<br />
[[Category:$Functions|$ProcGet]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$ProcOpn&diff=116802$ProcOpn2018-09-20T22:32:36Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$ProcOpn}}<br />
<span class="pageSubtitle">Open procedure for $ProcDat, $ProcGet, $ProcLoc</span><br />
<br />
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ProcOpn function.</p><br />
<br />
The <var>$ProcOpn</var> function is used to "open" a procedure as input to a <var class="product">SOUL</var> procedure via <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> (or the deprecated <var>[[$ProcGet]]</var> and <var>[[$ProcDat]]</var>) or via <var>[[$ProcLoc]]</var>. <br />
<br />
<var>$ProcOpn</var> accepts three arguments and returns a numeric code. It is also a [[Calling Sirius Mods $functions|callable]] $function.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ProcOpn</span>(<span class="term">proc_name</span>, [<span class="term">file_name</span>], <span class="term">inc_string</span>)<br />
</p><br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%result</th><br />
<td>A numeric return code that indicates the success of the function. (Return codes are [[#retCodes|listed below]].)</td></tr><br />
<br />
<tr><th>proc_name</th><br />
<td>This argument is required; it identifies the <var class="product">SOUL</var> procedure to be opened. </td></tr><br />
<br />
<tr><th>file_name</th><br />
<td>An optional file name. If this argument is not provided or is a null string, the current file is used. </td></tr><br />
<br />
<tr><th>inc_string</th><br />
<td>A string that is used by <var>$ProcGet</var> for dummy string substitution, just as if this argument had been placed on an <var>Include</var> statement. <br />
<p class="note"><b>Note:</b> <var>$ProcDat</var> does no dummy string substitution. </p><br />
</table><br />
<br />
===<b id="retCodes"></b>Return codes===<br />
<p class="code">-1 - Current include level not opened by $ProcOpn<br />
0 - Procedure opened without errors<br />
1 - Procedure is locked for edit or delete<br />
2 - Procedure does not exist or the current user does not have access privilege<br />
3 - Specified procedure name is invalid (null)<br />
4 - File name invalid, or no current file, or caller does not have sufficient <br />
privilege to display/include procedures<br />
5 - The maximum number of open procedures (5) has already been reached<br />
6 - Insufficient space in ITBL to hold third argument; increase the size of ITBL<br />
</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li>After <var>$ProcOpn</var> has successfully opened a procedure, <var>$ProcGet</var> and <var>$ProcDat</var> may be used to retrieve the procedure source lines, and <var>$ProcLoc</var> may be used to scan the lines. </li><br />
<br />
<li>If a "temporary request" (a negative number or zero) is<br />
specified for <var class="term">proc_name</var> that does not exist (this includes numbers<br />
outside the range of the <var>[[NORQS parameter|NORQS]]</var> parameter), an error condition may result. For example:<br />
<br />
<p class="code">$procOpn(-9999)<br />
</p><br />
<br />
When the above fragment is executed, the following error occurs<br />
(but the request continues to run):<br />
<br />
<p class="code">M204.1186: Bad previous request number</p><br />
<br />
The value <code>0</code> is returned by <var>$ProcOpn</var>, and<br />
the procedure is treated as an empty procedure. This probably<br />
works properly for most applications.<br />
<br />
<p class="note"><b>Beware:</b> If your application<br />
passes such non-existing temporary request numbers to <var>$ProcOpn</var>,<br />
your request may be subject to request cancellation due to<br />
exceeding <var>[[ERMX parameter|ERMX]]</var>.</p></li><br />
</ul><br />
<br />
==Examples==<br />
Suppose procedure <code>TIS_PITY</code> in procedure file <code>HOHO</code> contains this line:<br />
<p class="code">FIND1: IN ?? FIND ALL RECORDS FOR WHICH<br />
</p><br />
<br />
Then this sequence:<br />
<p class="code">%result = $ProcOpn('TIS_PITY', 'HOHO', ' THESE ARE ARGUMENTS') <br />
%line = $ProcGet<br />
</p><br />
<br />
Results in <code>%line</code> being set to:<br />
<p class="code">FIND1: IN THESE FIND ALL RECORDS FOR WHICH<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]<br />
<li>[[Fast/Unload SOUL Interface]]<br />
<li>[[Janus Web Server]]<br />
</ul><br />
<br />
[[Category:$Functions|$ProcOpn]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$DelCh&diff=116795$DelCh2018-09-20T22:01:12Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius funcitons"</p>
<hr />
<div>{{DISPLAYTITLE:$DelCh}}<br />
<span class="pageSubtitle">Remove characters from string, compress and strip blanks</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $DelCh function is the <var>[[Remove (String function)|Remove]]</var> function.</p><br />
<br />
This function removes specified characters from an input string and performs blank compression and stripping. <br />
<br />
The <var>$DelCh</var> function accepts four arguments and returns a string result that is part of the first argument string. <br />
<br />
The first argument is an arbitrary string. <br />
<br />
The second argument is the set of characters to be removed from the first argument string. <br />
<br />
The third argument is a starting position in the first argument string. <br />
<br />
The fourth argument is a number indicating the type of blank compression or stripping to be performed. Valid numbers and their meanings are:<br />
<br />
<ol><br />
<li>delete the specified characters <br />
<li>delete the specified characters and strip leading and trailing blanks <br />
<li>delete the specified characters, strip leading and trailing blanks and compress multiple blanks to a single blank.<br />
</ol><br />
<br />
This is an optional argument and defaults to 1.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%STRING</span> = <span class="literal">$DelCh</span>(<span class="term">string</span>, <span class="term">chars</span>, <span class="term">start_pos</span>, [<span class="term">option</span>])<br />
</p><br />
<br />
<p>%STRING is part of the first argument string.</p><br />
<br />
==Examples==<br />
<ol><br />
<li>The following statement sets %JUNK to <tt>CD</tt>:<br />
<p class="code">%JUNK = $DelCh('ABCDAAAABAB', 'AB')<br />
</p><br />
<br />
<li>This statement sets %JUNK to <tt>W HAV WAITD LONG NOUGH</tt>:<br />
<p class="code">%JUNK = $DelCh(' WE HAVE WAITED LONG ENOUGH ', 'E', , 3)<br />
</p><br />
<br />
<li>This statement sets %JUNK to <tt>WE HAV AITD ONG NOUGH</tt>:<br />
<p class="code">%JUNK = $DelCh(' WE HAVE WAITED LONG ENOUGH ', 'WEL', 5, 3)<br />
</p><br />
</ol><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]</li><br />
<li>[[Fast/Unload User Language Interface]]</li><br />
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li><br />
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li><br />
<li>[[Janus Sockets]]</li><br />
<li>[[Janus Web Server]]</li><br />
<li>Japanese functions</li><br />
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$DelCh]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$Deflate&diff=116794$Deflate2018-09-20T21:59:55Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ fix "Sirius functions"</p>
<hr />
<div>{{DISPLAYTITLE:$Deflate}}<br />
<span class="pageSubtitle">Compress a longstring with Deflate</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Deflate function is the <var>[[Deflate (String function)|Deflate]]</var> function.</p><br />
<br />
This function compresses a longstring using the "deflate" algorithm. The deflate algorithm is described completely in RFC 1951. It is very effective with HTML and XML data. <br />
<br />
The <var>$Deflate</var> function accepts two arguments and returns a longstring result.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%lstrc</span> = <span class="literal">$Deflate</span>(%lstr, option)<br />
</p><br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%lstrc</th><br />
<td>The returned longstring.</td></tr><br />
<br />
<tr><th>%lstr</th><br />
<td>The longstring to be compressed; it is required. </td></tr><br />
<br />
<tr><th>option</th><br />
<td>A string that describes the type of compression to perform on the longstring. This argument is optional; if it is not specified, DYNAMIC compression is used. Valid options and their meanings are:<br />
<br />
<table class="syntaxTable"><br />
<tr><th><var>FIXED</var></th><br />
<td>Indicates that compression is done with fixed codes. The fixed code tables used for compression (defined as part of RFC 1951) are somewhat optimized for ASCII character data, but slightly decrease the amount of CPU required to perform compression. Also, since the codes are already defined as part of the specification, they are not included in the compressed data.</td></tr><br />
<br />
<tr><th><var>DYNAMIC</var></th><br />
<td>Indicates that the compression code tables are generated based on the input data. Dynamic tables typically provide somewhat better compression on most types of data. There is a very slight CPU overhead in computing the frequencies of byte values in the input data. Also, since the code tables are dynamic, they are included as part of the compressed data. This will increase the size of the compressed longstring, but these tables are small, since they are also stored in a compressed form.<br />
</td></tr></table><br />
</td></tr></table><br />
<br />
==Usage notes==<br />
<ul><br />
<li> If an invalid option is passed, or compression is not enabled for the current run, the request is cancelled. <br />
<li> The NCMPBUF parameter must be set by User 0 before the <var>$Deflate</var> function can be used. If <var>$Deflate</var> is called with NCMPBUF = 0, the request is cancelled. <br />
<li> As with any compression scheme, it is possible that a particular string will become longer after compression. This would happen, for example, if a deflated string were passed to <var>$Deflate</var>. <br />
<li> Short strings (less than 128 bytes) will typically compress better with the FIXED option.<br />
</ul><br />
<br />
==Example==<br />
In the following example, %LSTRC is set to the compressed version of the given string:<br />
<p class="code"> %LSTRC = $Deflate('How much wood could a woodchuck chuck', 'FIXED')<br />
</p><br />
<p>'''Note: ''' No other string or longstring functions can be usefully performed on the compressed string until it is decompressed with <var>[[$Inflate]]</var>. <br />
<br />
==Products authorizing $Deflate==<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]</li><br />
<li>[[Fast/Unload User Language Interface]]</li><br />
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li><br />
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li><br />
<li>[[Janus Sockets]]</li><br />
<li>[[Janus Web Server]]</li><br />
<li>Japanese functions</li><br />
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$Deflate]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$Delimr&diff=116793$Delimr2018-09-20T21:58:58Z<p>JAL: fix "Sirius functions" link</p>
<hr />
<div>{{DISPLAYTITLE:$Delimr}}<br />
<span class="pageSubtitle">Insert delimiter string into input string at regular positions</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Delimr function is the <var>[[Insert (String function)|Insert]]</var> function.</p><br />
<br />
This function inserts a delimiter string into an input string at regular positions. The <var>$Delimr</var> function accepts three arguments and returns a string result that is made up of the first argument string and the delimiters. <br />
<br />
The first argument is an arbitrary string. <br />
<br />
The second argument is a delimiter string that is truncated at two characters if longer. <br />
<br />
The third argument is a number that indicates the intervals at which to insert the delimiter string. If this argument is omitted, the delimiter string is not inserted.<br />
==Syntax==<br />
<p class="syntax"><span class="term">%STRING</span> = <span class="literal">$Delimr</span>(<span class="term">string</span>, <span class="term">delim</span>, <span class="term">interval</span>)<br />
</p><br />
<p><br />
</p><br />
<p>%STRING is made up of the first argument string and delim.</p><br />
<br />
For example<br />
<p class="code"> %JUNK = $Delimr('070476', '/', 2)<br />
</p><br />
would set %JUNK to <tt>07/04/76</tt> and<br />
<p class="code"> %JUNK = $Delimr('ABCDEFG', ' ', 1)<br />
</p><br />
would set %JUNK to <tt>A B C D E F G</tt>.<br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]</li><br />
<li>[[Fast/Unload User Language Interface]]</li><br />
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li><br />
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li><br />
<li>[[Janus Sockets]]</li><br />
<li>[[Janus Web Server]]</li><br />
<li>Japanese functions</li><br />
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$Delimr]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=Release_notes_for_Model_204_version_7.7&diff=116787Release notes for Model 204 version 7.72018-09-13T16:13:28Z<p>JAL: /* New in this release */ add nbsp</p>
<hr />
<div>These release notes list the enhancements and other changes contained in Model 204 version 7.7. <br />
<br />
==Overview==<br />
These release notes contain installation and features information for the Rocket Model 204 version 7.7 release.<br />
Before beginning your installation, please read through this information about product installation and changes.<br />
<br />
==New in this release==<br />
The table below cites some highlights of Model&nbsp;204 version 7.7. For a full list of features, refer to the Table of Contents. <br />
<table><br />
<tr class="head"><th>Category</th><br />
<th>Feature</th></tr><br />
<br />
<tr><br />
<td>Performance</td><br />
<td><br />
<ul><br />
<li>Continued expansion of 64-bit addressability. See [[#Elimination of BTB buffers|Elimination of BTB buffers]]. </li><br />
<br />
<li>Greater zIIP processor availability: M204 HPO and Fast/Unload HPO. See [[#zIIP exploitation|zIIP exploitation]]. </li><br />
<br />
<li>zIIP load tuning. See [[#MPDELAY and MPDELAYZ (new)|MPDELAYZ]], [[#SCHDOFLS (new)|SCHDOFLS]], [[#SCHDOPT (change to X'20' bit processing)|SCHDOPT]]. </li><br />
<br />
<li>Essential removal of application limits on the [[#Increase in request limit for number of images, screens, and menus|number of images, screens, and menus]].</li><br />
<br />
<li>Support for large data sets (as many as 16 million tracks) for the Model&nbsp;204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. See [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].</li><br />
</ul><br />
</td></tr><br />
<br />
<tr><br />
<td>Security</td><br />
<td><br />
<ul><br />
<li>Stronger cryptographic algorithms: SHA-384, SHA-512. See [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]]. </li><br />
<br />
<li>Longer RSA keys (as many as 4096 bits). See [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]]. </li><br />
<br />
<li>Support for [[#Long password support|longer and mixed-case login passwords]]. </li><br />
</ul><br />
</td><tr><br />
<br />
<tr><br />
<td nowrap>Add-on enhancements</td><br />
<td><br />
<ul><br />
<li>A more versatile Fast/Unload through [[#Integration of Fast/Unload with the Online load module|integration with Model&nbsp;204]]. </li><br />
<br />
<li>Janus products' [[#Support for IPV6|support for the IPV6 network protocol]], expanding the network address space from 32 to 128 bits. </li><br />
</ul><br />
</table><br />
<br />
==Operating system and hardware requirements==<br />
<br />
===Operating system requirements===<br />
<br />
<ul><br />
<li><b>IBM z/OS versions supported:</b> <br />
<ul><br />
<li>All IBM supported releases up to and including z/OS 2.3. <br />(For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li><br />
<p>Version 1.07 is sufficient for all functionality except for the following features:</p><br />
<ul><br />
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li><br />
<li>Large (1 MB) page support requires version 1.9.</li><br />
<li>Extended address volumes (EAV) requires version 1.12.</li><br />
</ul><br />
</li><br />
</ul><br />
On z/OS, Model 204 release 7.7 operates as an APF authorized load module, as required by many 7.7 features. <br /><br />
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].<br />
<br />
<li><b>IBM z/VM versions supported:</b> <br />
<ul><br />
<li>All IBM supported releases up to and including z/VM 6.3.</li><br />
</ul><br />
</li><br />
<br />
<li><b>IBM z/VSE versions supported:</b><br />
<ul><br />
<li>All IBM supported releases up to and including z/VSE 6.1.</li><br />
</ul><br />
</li><br />
</ul><br />
<br />
===Hardware requirements===<br />
<br />
In general, Model 204 version 7.7 requires the IBM z/890 or above processor.<br />
<p>However, the IBM z10 or above processor is required for the following features:<br />
<ul><br />
<li>large (1 MB) page support</li><br />
<li>IBM's High Performance FICON (zHPF) support</li><br />
</ul></p><br />
<br />
===Model 204 compatibility with operating systems===<br />
<br />
For information on Model 204 certification with IBM operating systems, see [[Model 204 system requirements]].<br />
<br />
===Connect<sup>&#9733;</sup> compatibility with Model 204===<br />
<br />
Connect<span class="superstar">&#9733;</span> version 7.5 or 7.7 is compatible with Model 204 version 7.7.<br />
<br />
For more information on Connect<span class="superstar">&#9733;</span> installation, see the [[:Category:Connect*|Connect<span class="superstar">&#9733;</span> wiki pages]].<br />
<br />
==SOUL (User Language) enhancements==<br />
<br />
<br />
<br />
===New and changed classes and methods===<br />
<br />
====New exception class: WriteError====<br />
<var>[[WriteError class|WriteError]]</var> exceptions are thrown by the <var>Close</var>, <var>WriteBlock</var>, <var>WriteRecord</var>, and <var>WriteRecords</var> methods in the [[Dataset class]] if they encounter a full output <var>Dataset</var> object.<br />
<br />
====New default certificate-signing algorithm====<br />
[[Janus Network Security]] as well as the <var>[[Stringlist_class|StringList]]</var> methods <var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var> and <var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var> methods have changed their default signature algorithm from SHA-1 to SHA-256.<br />
<br />
This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model&nbsp;204.<br />
<br />
===="SSL" String methods====<br />
These new methods are added:<br />
<table><br />
<tr class="head"><th>Method</th><th>Description</th></tr><br />
<tr><td>[[SHA384digest (String function)|SHA384digest]]</td><td>SHA-384 digest</td></tr><br />
<tr><td>[[SHA512digest (String function)|SHA512digest]]</td><td>SHA-512 digest</td></tr><br />
</table><br />
<br />
====New LoadMsgctl method====<br />
The new <var>[[LoadMsgctl (XmlDoc subroutine)|LoadMsgctl]]</var> method lets you view what <var class="product">Model&nbsp;204</var> messages have been affected by <var>[[MSGCTL command|MSGCTL]]</var> commands. The method also displays the current attributes of those messages. <!-- PDS-6119 --><br />
<br />
In addition, to better understand the effect of the <var>MSGCTL</var> command, the [[RKTools]] <code>SIRIUS</code> file will contain a procedure you can use to display the <var>MSGCTL</var> commands that have been specified in the Online session.<br />
<br />
====New DigestAlgorithm values====<br />
Values <var>SHA384</var> and <var>SHA512</var> are added to the [[DigestAlgorithm enumeration]].<br />
<br />
====Method variable invocation====<br />
[[Method variables]] can now be invoked using <code>%var()</code> or <code>%obj:var()</code>, as in JavaScript.<br />
<br />
====X509CertificateToXmlDoc method support for unknown elements====<br />
A certificate's <code>&lt;RelativeDistinguishedName&gt;</code> element can contain a wide variety of attributes that <var>X509CertificateToXmlDoc</var> does not understand. Under Model&nbsp;204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <code>&lt;unknown&gt;</code> elements with an <code>&lt;ObjectIdentifier&gt;</code> element that indicates the ASN.1 object identifier. <br />
<br />
<p class="note"><b>Note:</b> You are advised not to refer to such an <code>&lt;unknown&gt;</code> element in your programs, since future updates to the <var>X509CertificateToXmlDoc</var> method might add support for the element, in which case the element name will change to a proper name. If such an element is of interest, [[Contacting Rocket Software Technical Support|contact Rocket Software technical support]]. </p><br />
<br />
====Resulting element length in "ToXmlDoc" String methods====<br />
Prior to version 7.7 of Model&nbsp;204, the <var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, <var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var>, <var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var>, and<br />
<var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> methods failed if input to them created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters. <br />
An example of such input is a 4096-bit key (which requires 1024 hex characters).<br />
<br />
As of version 7.7, the lengths of the created text nodes are not restricted.<br />
<br />
====LDAP request length limit====<br />
Prior to version 7.7 of Model&nbsp;204, the SOUL [[LDAP class#limit|LDAP client buffers]] allowed a limit of 6144 bytes per request. As of 7.7, the limit is increased to 8184.<br />
<br />
===New XHTML entities for square-bracket characters===<br />
<b>&lsqb;</b> and <b>&rsqb;</b> are newly supported as [[XML processing in Janus SOAP#Entity references|XMHTL entities]] (notably in the [[U (String function)#brackets|U method]]). This provides a better approach to specifying square brackets (such as for [[XPath#Some notes on XPath usage|XPath]] expressions) than the formerly recommended use of <var>Static</var> %variables initialized to the correct values. <br />
<br />
This change is propagated by zap maintenance to version 7.6 of Model 204. <br />
<br />
For example, to produce an XPath expression equivalent to the following:<br />
<p class="code"><nowiki>*/pers[@name="Hector"] </nowiki></p><br />
Code like this was recommended under version 7.5 of Model&nbsp;204:<br />
<p class="code">%lsq is string len 1 static initial('&amp;#x5B;'):u<br />
%rsq is string len 1 static initial('&amp;#x5D;'):u<br />
. . . <br />
%myXmldoc:print('*/pers' %lsq '@name="Hector"' %rsq) </p><br />
<br />
Under version 7.6 and above, you can instead use the new entities and avoid the declarations, concatenations, and runtime conversions required above:<br />
<p class="code">%myXmldoc:print('*/pers<b>&lsqb;</b>@name="Hector"<b>&rsqb;</b>':u)</p><br />
<br />
===Procedure names can begin with zero===<br />
Formerly, a procedure name was not allowed to begin with a zero or a minus sign. As of version 7.7, a procedure name can begin with a zero, and alphanumeric procedure names can begin with a minus sign (<tt>-</tt>), which is interpreted as a hyphen. For example, <code>00123</code>, <code>-1myproc</code>, and <code>-myproc</code> are valid procedure names. <br />
<p><br />
See the <var>[[PROCEDURE command|PROCEDURE]]</var> command for details. </p><br />
<br />
===Assert statement support for Info expressions===<br />
The SOUL <var>[[Assert statement|Assert]]</var> statement allows the optional parameter <var>Info</var> to provide additional output information. As of version 7.7, the <var>Info</var> phrase may contain any valid SOUL expression, including a method call or $function. The expression, which must be enclosed in parentheses, is evaluated only in the case of an <var>Assert</var> failure.<br />
<br />
A simple example is:<br />
<p class="code">assert %x gt 0, info ('abc' with 'def') </p><br />
<br />
<blockquote class="note"><br />
<p><b>Note:</b> This enhancement introduces a slight backward incompatibility: An <var>Assert</var> statement like the following, whose <var>Info</var> value begins with an opening parenthesis but has no closing parenthesis, compiled without error prior to version 7.7: </p><br />
<p class="code">assert %x gt 0, info (</p> <br />
<p><br />
From 7.7 on, such a statement produces a compilation error, because the compiler expects an expression after the open parenthesis. </p><br />
</blockquote><br />
<br />
==Security enhancements==<br />
===Long password support===<br />
<p><br />
Logon passwords, maintained in CCASTAT, can now contain as many as 127 characters. <br />
<br />Also, passwords and passphrases can now contain one or more embedded spaces. (Leading and trailing spaces are stripped.)</p><br />
<p><br />
The long password feature includes support for: </p><br />
<ul><br />
<li><var>[[LOGIN or LOGON command|LOGON]]</var> command</li><br />
<li><var>[[LOGINCP or LOGONCP command|LOGONCP]]</var> command, used to change a password</li><br />
<br />
<li><var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL C USERID]]</var> command</li><br />
<br />
<li><var>[[$Sir_Login]]</var> function</li><br />
<br />
<li>Mixed-case passwords (if the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter includes the value 11)</li><br />
<br />
<li>[[Storing_security_information_(CCASTAT)|CCASTAT]] data sets created with or without password expiration support</li><br />
<br />
<li>Long passwords (passphrases) for use with the following [[Security interfaces overview|external security interfaces]]: CA-ACF2 MVS, Security Server (formerly RACF), and CA-Top Secret</li><br />
</ul><br />
<p class="note"><b>Note:</b> This feature is available for logon passwords only; it does not apply to file passwords.</p> <br />
<p><br />
No changes to CCASTAT and no new CCAIN parameters are required to enable long password support.</p><br />
<p>In order to allow embedded blanks in passwords passed on [[IFSTRTN_(IFAM2)_(HLI_function)|IFSTRTN]] calls, a semicolon is required as the password delimiter and the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter 24 value must be set.</p><br />
<br />
For additional security enhancements in version 7.7, see [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]] as well as [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]].<br />
<br />
==Janus product enhancements==<br />
<br />
===<b id="IPV6"></b>Support for IPV6===<br />
As of version 7.7, customers can use the [[Janus products]] in an IPV6 (Internet Protocol Version 6) environment. Before this release, all Janus commands and parameters were able to accommodate IPV4 addresses only. IPV6 addresses expand the network address space from 32 to 128 bits.<br />
<br />
These parameters, commands, and functions support IPV6 under version 7.7 of Model&nbsp;204:<br />
<br />
<table><br />
<tr class="head"><th>Commands</th><th>System parameter</th><th>SOUL</th></tr><br />
<tr><td nowrap><br />
JANUS CLSOCK and JANUS SRVSOCK <br><br />
JANUSDEBUG and JANUS WEB DEBUG <br><br />
JANUS DEFINEIPGROUP <br><br />
JANUS DEFINE BINDADDR <br><br />
JANUS DISIPG <br><br />
JANUS DISUSG <br><br />
JANUS TRACE <br><br />
JANUS WEB ALLOW <br />
</td><br />
<br />
<td nowrap><br />
TCPTYPE <br><br />
(see [[#tcptype|TCPTYPE (new IPV6 values)]])<br />
</td><br />
<br />
<td nowrap><br />
$Web_IPAddr <br><br />
LocalHost (UdpSocket property) <br />
</td></tr><br />
</table><br />
<br />
===Janus Network Security ciphers and private keys===<br />
Support for certificates signed using [[DigestAlgorithm_enumeration|SHA-384 and SHA-512]] are added to [[Janus Network Security]]. This makes it possible to generate certificates signed with these algorithms and to accept server or client certificates signed with these algorithms.<br />
<br />
In addition, support is added for RSA keys that are as many as 4096 bits in length. You can now generate and sign 4096-bit keys and use them in client and server certificates using <var class="product">Janus Network Security</var> application as well as its associated and related methods, including:<br />
<table><br />
<tr class="head"><th>Class</th><th>Method</th></tr><br />
<tr><td>System</td><br />
<td><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var></td></tr><br />
<br />
<tr><td rowspan="4">Stringlist</td> <br />
<td><var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var></td></tr><br />
<br />
<tr><td><var>[[AppendGeneratedPrivateKey (Stringlist subroutine)|AppendGeneratedPrivateKey]]</var></td></tr><br />
<br />
<tr><td><var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var></td></tr><br />
<br />
<tr><td><var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var></td></tr><br />
<br />
<tr><td rowspan="4">String</td><br />
<td><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </td></tr><br />
<br />
<tr><td><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </td></tr><br />
<br />
<tr><td><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> </td></tr> <br />
<br />
<tr><td><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </td></tr><br />
</table><br />
<br />
===Janus Web Server rules===<br />
The following changes have been made in version 7.7:<br />
<ul><br />
<li>Janus Web used to automatically implement [[Defining Web rules#Notes|two web server ON rules]] to set up access to the Janus Web sample home page and to demonstration application procedures. These rules were removed in version 7.6 (by zap maintenance) and are not present in version 7.7.</li><br />
<br />
<li>You can now substitute an HTTP method name in the command for a <var>JANUS WEB ON</var> rule. See [[#ON rules (method name substitution)|ON rules (method name substitution)]] for details.</li><br />
<br />
<li>The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed <i>for non-SSL ports</i> to the following:<br />
<p class="code">JANUS WEB <i>portname</i> DISALLOW *<br />
</p><br />
<p><br />
This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.<br />
The rule applies (after zap 77Z088 in version 7.7, or after zap 76Z418 in version 7.6) unless overridden by user-added rules. <br />
</p><br />
<blockquote class="note"><br />
<p><b>Note:</b> With version 7.7 zap 77Z090 or version 7.6 zap 76Z420, you can make the default <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>). To do so, turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: </p><br />
<p class="code">RESET WEBDFLT=1</p><br />
</blockquote></li><br />
<br />
<li>As described below in [[#JANUS WEB (additional rule support)|JANUS WEB (additional rule support)]], the <var>JANUS WEB</var> command <var>ALLOW</var> and <var>DISALLOW</var> rules are updated to include support for RESTful and WebDAV HTTP methods. </li><br />
</ul><br />
<br />
===Janus Web access to HTTP authorization and authentication headers===<br />
Under version 7.7, Janus Web lets you access HTTP user authentication headers. You can capture the HTTP "Authorization" request header value, and you can set the "WWW-Authenticate" response header. See [[Janus Web Server security#Authorization and WWW-Authenticate headers|Authorization and WWW-Authenticate headers]].<br />
<br />
==Fast/Unload enhancements==<br />
<br />
===<b id="funldIntegrat"></b>Integration of Fast/Unload with the Online load module ===<br />
<!-- PDS-5869 --><br />
Previously (for all versions of <var class="product">Fast/Unload</var> through 4.7), the standalone <code>FUNLOAD</code> load module was downloaded and linked separately and independently from Model&nbsp;204. Starting with version 7.7 of Model&nbsp;204:<br />
<ul><br />
<li><var class="product">Fast/Unload</var> is entirely linked with the Model&nbsp;204 Online load module. </li><br />
<br />
<li>Maintenance zaps applied to the Online load module include all <var class="product">Fast/Unload</var> maintenance.</li><br />
<br />
<li>The version number of <var class="product">Fast/Unload</var> is the same as the version number of Model&nbsp;204. </li><br />
<br />
<li>If you are authorized for Fast/Unload, the authorization zap for the ONLINE load module will contain authorization for Fast/Unload. The authorization zap used for previous releases of FUNLOAD should not be applied to the FUNLOAD module in 7.7.</li><br />
</ul><br />
<br />
Under 7.7, the Online load module can be linked with an ALIAS (the standard one is FUNLOAD) and an alternate ENTRY. This alias is functionally indistinguishable from the standalone <var class="product">Fast/Unload</var> FUNLOAD load module installed for all previous versions of <var class="product">Fast/Unload</var>. <br />
<br />
The integration of Fast/Unload with the Online load module also makes additional DDnames available to PGM=FUNLOAD for possible problem diagnosis by Rocket Technical Support. These DDnames are <code>CCASNAP</code>, <code>CCAAUDIT</code>, and <code>CCAPRINT</code>, and they are described in [[Fast/Unload invocation#ccadd|Fast/Unload invocation]].<br />
<br />
A significant benefit of running Fast/Unload integrated with Model&nbsp;204 and not standalone is the ability to take advantage of zIIP processing, as described next in the "zIIP exploitation" section.<br />
<br />
===zIIP exploitation===<br />
If you have an authorization zap that contains both of the following, your standalone PGM=FUNLOAD jobs will run on a zIIP processor, if one is available:<br />
<ul><br />
<li><var class="product">[[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|M204 HPO]]</var>, the zIIP-support product of Model&nbsp;204<br />
<p><br />
PGM=FUNLOAD automatically supplies the necessary Model&nbsp;204 parameters to enable zIIP exploitation. </p></li><br />
<br />
<li>The <var class="product">[[Fast/Unload overview#fuhpo|Fast/Unload HPO]]</var> product </li><br />
</ul><br />
<br />
===New #VIEW204 function===<br />
The <var>[[Fast/Unload standard functions#.23VIEW204: Value of Model 204 parameter|#VIEW204]]</var> function returns the value of the [[List of Model 204 parameters|Model&nbsp;204 parameter]] you specify as an argument.<br />
<br />
===PUT statement enhancements===<br />
<!-- PDS-6107 --><br />
<br />
====Length prefix for PUT output values====<br />
<!-- PDS-5871 --><br />
New <var>[[Fast/Unload PUT statement#PUT|PUT]]</var> statement syntax is added to insert a one-byte or two-byte binary integer, containing the byte length of a <var>PUT</var> value, in the output stream before the value. <br />
<br />
For better readability and lower CPU cost than the techniques currently used to achieve the same result, the <var>AS</var> clause of a <var>PUT</var> statement will now allow the <var>COUNTED</var> keyword:<br />
<p class="code">... PUT <i>info</i> .. AS [<i>format</i>] COUNTED[1|2] </p><br />
<p><br />
For example, <code>PUT FIRST.NAME AS COUNTED2</code> puts the first occurrence of field <code>FIRST.NAME</code> as a string value, preceded by a two-byte binary integer containing the length of that occurrence.</p><br />
<p><br />
With this feature, you can replace FUEL code such as the following: </p><br />
<p class="code">%VAL = ITEM.CODE(%OCC)<br />
%LEN = #LEN( %VAL )<br />
PUT %LEN AS FIXED(2)<br />
PUT %VAL </p><br />
<p>With: </p><br />
<p class="code">PUT %VAL AS COUNTED2 </p><br />
<br />
====#function as PUT "info" argument====<br />
<!-- PDS-5871 --><br />
New in this version, a #function call is allowed as the <var>PUT</var> <var class="term">info</var> argument. For example, instead of FUEL code such as the following:<br />
<p class="code">%VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0)<br />
PUT %VAL </p><br />
You can use this more readable and somewhat more efficient equivalent:<br />
<p class="code">PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0) </p><br />
<br />
===#STRIP function enhancements===<br />
<!-- PDS-5871 --><br />
<br />
====New #STRIP fourth argument====<br />
<!-- PDS-5871 --><br />
The new fourth argument of <var>[[Fast/Unload standard functions##strip|#STRIP]]</var> lets you designate a <var>#STRIP</var> first-argument value to be nullified. That is, when the value of the first argument is equal to the value of the fourth argument, <var>#STRIP</var> returns a null string. You might use this optional argument for fields that have a "placeholder value" or "default value" which is not actual data.<br />
<br />
This argument can be conveniently combined with the<br />
new <var>[[#Length prefix for PUT output values|COUNTED]]</var> options for <var>PUT</var>, because a length-prefixed format allows a reliable, unambiguous representation of a series of null strings. <br />
<p><br />
Combining the new fourth argument, the new <var>COUNTED2</var> option, and the new [[#optn|N option]] of the second argument provides a simpler alternative to FUEL code such as the following:</p><br />
<p class="code">%VAL = ITEM.STRING(%OCC)<br />
IF %VAL EQ '_' THEN<br />
PUT 0 AS FIXED(2)<br />
ELSE<br />
%LEN = #LEN(%VAL)<br />
PUT %LEN AS FIXED(2)<br />
PUT %VAL<br />
END IF<br />
</p><br />
<p><br />
You can replace the above statements by the more readable and efficient: </p><br />
<p class="code">PUT #STRIP(ITEM.STRING(%OCC), 'N', , '_') AS COUNTED2<br />
</p><br />
<br />
====New #STRIP type options====<br />
<!-- PDS-5871 --><br />
<var>P</var> and <var>N</var> strip-type options are added to the <var>#STRIP</var> function:<br />
<ul><br />
<li>The new <var>P</var> option strips all but one leading <var class="term">pad</var>-argument characters from the <var>#STRIP</var> first argument returned value, if that value contains a non-zero length string of only <var class="term">pad</var> characters. <br />
<p><br />
<var>P</var>, together with other new Fast/Unload <var>PUT</var> features, provides a simpler alternative to FUEL code such as the following:</p><br />
<p class="code">%VAL = ITEM.NUMBER(%OCC)<br />
IF %VAL EQ '_' OR %VAL EQ &apos;' THEN<br />
PUT 0 AS FIXED(2)<br />
ELSE<br />
%VAL = #STRIP(%VAL, 'L', '0')<br />
IF %VAL EQ &apos;' THEN<br />
%VAL = '0'<br />
END IF<br />
%LEN = #LEN(%VAL)<br />
PUT %LEN AS FIXED(2)<br />
PUT %VAL<br />
END IF </p><br />
<p><br />
You can replace the above statements with the following, which outputs a numeric value with leading zeroes stripped: </p><br />
<p class="code">PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2<br />
</p><br />
<p class="note"><b>Note:</b> A FUEL <var>IF</var> statement oddity is that the precedence of <var>AND</var> and <var>OR</var> are the same.</p></li><br />
<br />
<li id="optn">The new <var>N</var> option strips neither leading-characters nor trailing-characters. <br />
<p><br />
For an example, see [[#New #STRIP fourth argument|New #STRIP fourth argument]], above.</p></li><br />
</ul><br />
<br />
==New and changed commands==<br />
<!--<br />
******************************************************************<br />
Please keep the following subsections alphabetized by command name<br />
******************************************************************<br />
--><br />
<br />
===AUTHCTL VIEW (additional information displayed)===<br />
The <var>[[AUTHCTL command#Example|AUTHCTL]]</var> command output now includes a list of the available sets of control parameters for the external security interface you specify in the command.<br />
<br />
===DISPLAY MODMAP (new parameter: <var>UEX</var>)===<br />
The <var>[[DISPLAY MODMAP command|DISPLAY MODMAP]]</var> command now has a <var>UEX</var> parameter that displays the entry point addresses of all defined user exits.<br />
<br />
===FREE command (new message)===<br />
Prior to this release, a successful <var>[[FREE command#msg|FREE]]</var> command was not followed by a message indicating success. Under version 7.7, <var>FREE</var> now indicates success with the following message:<br />
<p class="code">M204.0510: FREE command successful; <i>ddname</i> freed </p><br />
<br />
Also new in this release, a <var>FREE</var> command that takes no action because the specified file does not exist or is not allocated is now followed by an explanatory message:<br />
<br />
<p class="code">M204.0509: No action taken by FREE command; <i>ddname</i> not allocated </p><br />
<p><br />
In earlier versions, no such message followed. </p><br />
<br />
===JANUS DEFINE (new parameter: <var>SSLTRUST</var>)===<br />
The <var>[[JANUS DEFINE]]</var> command now has an <var>[[SSLTRUST (JANUS DEFINE parameter)|SSLTRUST]]</var> parameter that indicates that the certificate presented by the other side of a TLS/SSL connection is to be accepted even if it is not signed by a known certifying authority.<br />
<br />
===JANUS WEB (additional rule support)===<br />
<!-- PDS-5984 --><br />
<br />
====Expanded ALLOW/DISALLOW rules====<br />
The <var>[[JANUS WEB]]</var> command <var>ALLOW</var>/<var>DISALLOW</var> rules are updated to include support for these HTTP methods:<br />
<ul><br />
<li>The RESTful ([https://en.wikipedia.org/wiki/Representational_state_transfer Representational State Transfer]) methods CONNECT, DELETE, OPTIONS, PATCH, and TRACE. </li><br />
<br />
<li>The WebDAV ([http://www.webdav.org/specs/rfc4918.html Distributed Authoring and Versioning]) methods PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. </li><br />
</ul><br />
<br />
====ON rules (method name substitution)====<br />
In a version 7.7 <var>[[JANUS WEB ON|JANUS WEB ON]]</var> command, you can now reference the name of the HTTP method that is associated with the incoming request. To do this, specify an <code>M</code> after the escape (<tt>"</tt>) character, as in: <br />
<br />
<p class="code">JANUS WEB WEBPORT ON /TEST/* OPEN FILE TEST CMD 'I "M.*'</p><br />
<br />
A GET request for URL <code>/test/foo</code> would result in the file <code>TEST</code> being opened and the command <code>I GET.FOO</code> being issued. A POST for the same URL would result in the command <code>I POST.FOO</code> being issued.<br />
<br />
<p class="note"><b>Note:</b> This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>.</p><br />
<br />
===LOGINCP or LOGONCP (new)===<br />
Because colons are now valid password characters, the <var>[[LOGINCP or LOGONCP command|LOGINCP]]</var> (LOGIN and Change Password) command replaces the former technique for changing passwords using <var>LOGIN</var>. <br />
<p>Before version 7.7, with <var>LOGIN</var>, you specified <var class="term">oldpassword</var><tt>:</tt><var class="term">newpassword</var> in response to the <code>M204.0347: Password</code> prompt.</p> <br />
With the <var>LOGINCP</var> command, you are prompted and re-prompted for the new password after successful logon:<br />
<p class="code"><b>LOGINCP USER1</b><br />
M204.0347: Password <br />
M204.0353: USER1 USER1 login 16 JUL 29 12.38 <br />
M204.2633: Enter new password <br />
M204.2633: Re-enter new password <br />
M204.0350: New password accepted <br />
M204.0345: CCASTAT updated <br />
</p><br />
<var>LOGONCP</var> is a synonym for <var>LOGINCP</var>.<br />
<br />
===ZHPF (new parameters: <i>filename</i> and *)===<br />
The <var>[[ZHPF command|ZHPF]]</var> command checks zHPF ability for the file currently opened by the user. <br />
<br />
As of Model 204 7.7, you can specify parameters to <var>ZHPF</var>:<br />
<ul><br />
<li><var class="term">filename</var>, to check a specific file</li><br />
<li>An asterisk (<tt>*</tt>), to check local files opened by all users</li><br />
</ul><br />
<br />
==New and changed parameters==<br />
<!--<br />
********************************************************************<br />
Please keep the following subsections alphabetized by parameter name<br />
********************************************************************<br />
--><br />
<br />
===CUSTOM (new and changed values)===<br />
====New values====<br />
The following values have been added to the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter in this release:<br />
<ul><br />
<li>The <code>CUSTOM=23</code> value always truncates the user ID to 10 characters.</li><br />
<br />
<li>The <code>CUSTOM=41</code> value allows recording of data on successful RACF user logins. The login data is shown in RACFRW batch reports.</li><br />
<br />
<li>The <code>CUSTOM=42</code> value allows the editing of procedure names containing the following special characters: comma, equal sign, space, single quote, semicolon.</li> <br />
</ul><br />
<br />
====Changed value====<br />
<ul><br />
<li>The <code>CUSTOM=11</code> value also supports special-characters for RACF passwords as of version 7.7.</li><br />
</ul><br />
<br />
===LFSCB (new default/minimum value)===<br />
The default (and minimum) value of <var>[[LFSCB parameter|LFSCB]]</var> is now 8 bytes.<br />
<br />
===LITBL (new default/minimum value)===<br />
The default (and minimum) value of <var>[[LITBL parameter|LITBL]]</var> is now 8 bytes.<br />
<br />
===MINDEBCL (new)===<br />
The new system parameter, <var>[[MINDEBCL parameter|MINDEBCL]]</var>, can be set in an Online to specify the minimum [[Debugger]] Client build number that can be used with that Online.<br />
<br />
===MPDELAY and MPDELAYZ (new)===<br />
For an [[Performance monitoring and tuning#Multiprocessing .28MP.2F204.29|MP/204]] Online, the <var>[[MPDELAY parameter|MPDELAY]]</var> and <var>[[MPDELAYZ parameter|MPDELAYZ]]</var> parameters are added to improve the efficiency of the MP scheduler. They reduce the cost of starting too many new subtasks for the amount of work to be done.<br />
<br />
===NUMBUF and NUMBUFG===<br />
As described below in [[#Elimination of BTB buffers|Elimination of BTB buffers]], setting <var>NUMBUFG</var> greater than 0 in version 7.7 forces <var>NUMBUF</var> to 0 (no buffer pool buffers reside below the bar). Not setting <var>NUMBUFG</var> or setting it to 0 (no buffers above the bar) allows the calculation of BTB buffers to remain as in previous versions.<br />
<br />
===SCHDOFL and SCHDOFLZ (new minimum value)===<br />
The new minimum value of <var>[[SCHDOFL parameter|SCHDOFL]]</var> and <var>[[SCHDOFLZ parameter|SCHDOFLZ]]</var> is 0. Before Model 204 7.7, their minimum allowed value was 1.<br />
<br />
===SCHDOFLS (new)===<br />
For z/OS system customers using <var class="product">Model&nbsp;204</var> zIIP support, the new <var>[[SCHDOFLS parameter|SCHDOFLS]]</var> system parameter helps you to regulate the zIIP processor workload. <br />
<br />
<var>SCHDOFLS</var> specifies both of the following: <br />
<ul><br />
<li>The target number of threads on the zIIP offload queue before a non-SRB MP subtask is dispatched to help the zIIP subtasks. </li><br />
<br />
<li>If started, how aggressively non-SRB MP subtasks pick up work from the zIIP offload queue. </li><br />
</ul><br />
<p><br />
This parameter applies to z/OS only.</p><br />
<br />
===SCHDOPT (change to X'20' bit processing)===<br />
The <var>[[SCHDOPT parameter|SCHDOPT]]</var> X'20' bit prevents the maintask from running work that is intended to run on a zIIP subtask (when zIIP subtasks are defined and activated). As of Model&nbsp;204 7.7, even when this bit is off, the maintask will run some of the zIIP work only if the zIIP subtasks appear to be saturated. Saturation is defined as a zIIP subtask queue length of at least <code>[[SCHDOFLZ parameter|SCHDOFLZ]]*[[AMPSUBZ parameter|AMPSUBZ]]</code>. <br />
<br />
Formerly, this saturation requirement was absent, allowing the maintask to take on more (possibly too much) of the zIIP workload.<br />
<br />
===SERVSIZE (new default/minimum value)===<br />
The minimum value for <var>[[SERVSIZE parameter|SERVSIZE ]]</var> is changed from zero to 65536. If <var>SERVSIZE</var> is explicitly set in CCAIN and its value is less than 64K, the following message is issued:<br />
<p class="code">M204.1149: SERVSIZE has been set to its minimum value: 65536<br />
</p><br />
<br />
If <var>SERVSIZE</var> was not set but was [[Defining the runtime environment (CCAIN)#Sizing user server areas|calculated by the system]] to a value less than 64K, the following message is issued:<br />
<p class="code">M204.0163: SERVSIZE increased to 65536<br />
</p><br />
<p><br />
This change is propagated by zap maintenance to versions 7.6, 7.5, and 7.4 of Model&nbsp;204. </p><br />
<br />
===<b id="tcptype"></b>TCPTYPE (new IPV6 values)===<br />
As part of the version 7.7 [[#IPV6|support for IPV6]], three new optional (IPV6-address-only) values are added to the <var>[[TCPTYPE parameter|TCPTYPE]]</var> parameter: <br />
<p class="code">IBMV6<br />
BPXV6<br />
IUCVV6<br />
</p><br />
<br />
==Performance enhancements==<br />
<br />
===Elimination of BTB buffers===<br />
As of version 7.7, any use of above-the-bar buffer pool (as invoked by a setting of the <var>[[NUMBUFG parameter|NUMBUFG]]</var> parameter greater than 0) will force all buffer pool buffers above the bar &mdash; no below-the-bar buffers will exist. In this case, the <var>[[NUMBUF parameter|NUMBUF]]</var> and <var>[[MINBUF parameter|MINBUF]]</var> parameters will be forced to 0, and the other parameters that affect BTB storage (<var>MAXBUF</var>, <var>SPCORE</var>, <var>LDKBMWND</var>, and <var>NLRUQ</var>) will be ignored.<br />
<br />
If you set <var>NUMBUFG</var> to 0, all buffers will be below the bar, and the settings of the BTB-related parameters will be respected and calculated as in pre-7.7 versions.<br />
<br />
===Increase in request limit for number of images, screens, and menus===<br />
These limits are increased to 4095 per request:<br />
<ul><br />
<li>The total number of [[Images|images]] for all blocks (formerly 256)</li><br />
<br />
<li>The maximum number of [[Menu statement or block#Menus and screens|menus and screens]] combined (formerly 256)</li><br />
</ul><br />
<br />
===Large checkpoint data sets===<br />
Support is added for large data sets (as many as 16 million tracks) for the Model&nbsp;204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. For details, see [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].<br />
<br />
==Statistics enhancements==<br />
<br />
===BLKO===<br />
The [[Using system statistics#System performance statistics|performance statistic]] BLKO now also reports invisible users that are blocked out. In previous releases, invisible users were not reported and BLKO remained virtually zero. The new BLKO value is more precise, and by summing BLKO, WTSV, BLKI, REDY, SWPG, and RUNG, you can now approximate USRS (average active users).<br />
<br />
For the <var>MONITOR</var> command, the [[ONLINE monitoring#User information in formatted displays|QUE column]] now reports new values OFFO and OFFI instead of OFFQ for invisible users:<br />
<ul><br />
<li>OFFO is invisible and blocked out. </li><br />
<li>OFFI is invisible and blocked in. </li><br />
</ul><br />
<p><br />
The BLKO QUE value continues to mean blocked out and visible (on some queue), and BLKI means blocked in and visible.</p><br />
<br />
===CCATDIFF and CCATDIFH===<br />
The [[Using system statistics#Description of statistics|CCATDIFF]] user and since-last statistic gets incremented each time a user allocates a CCATEMP page, and it gets decremented each time a user frees a page. Its value is not allowed to drop below zero. In the event of a CCATEMP page shortage, CCATDIFF gives system managers the possibility of determining a particular user that might be primarily responsible. <br />
<br />
<p class="note"><b>Note:</b> CCATDIFF is a rough guide, not definitive: it might give false high readings for some users, but it will indicate a user whose usage is extremely extraordinary. </p><br />
<br />
[[Using system statistics#Description of statistics|CCATDIFH]] is a since-last statistic that reports a request's CCATDIFF since-last highwater mark, useful to retrospectively determine which request was responsible for a massive CCATEMP usage spike. For example, it will record a request that allocated a large number of CCATEMP pages but freed the pages before the request ended.<br />
<br />
==Other enhancements==<br />
<br />
===MODEL 6 screen size and back-paging===<br />
As of Model 204 version 7.7 (and 7.5 or 7.6 with maintenance applied), a large <var>[[LOUTPB parameter|LOUTPB]]</var> value for [[Terminal MODEL 6 support|MODEL 6]] geometries is allowed, even if screen back-paging has been enabled. <br />
<br />
In previous releases, during initialization, if back-paging was enabled for the IODEV, <var>LOUTPB</var> was automatically reset to the limit that supported back-paging. <br />
<br />
Back-paging will now be disabled for any terminal with a <code>MODEL 6</code> screen geometry that requires more than 6142 bytes.<br />
<br />
===ECF calls to the IBM IDCAMS utility===<br />
The new <var>IDCAMS</var> option for the <var>[[External Call Facility#module|External Module]]</var> statement of the Model&nbsp;204 [[External Call Facility]] lets a SOUL program invoke IDCAMS without using the SYSIN and SYSPRINT DD statements. Instead, the Model&nbsp;204 Universal Buffer is used to pass the input lines and receive the output lines from IDCAMS.<br />
<br />
===<b id="ecfprofile"></b>Running ECF requests under the invoking user’s profile===<br />
<!-- see PDS-6158 -->Unless the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit is set, the job invoked by a privileged [[External Call Facility]] statement at a site where an external authorizer (ACF2, RACF, or Top/Secret) is used runs under the external-authorizer profile of the <i>user</i> that invokes the External Call, rather than under the <i>job's</i> external-authorizer profile. <br />
<br />
Prior to version 7.7, such a job always ran under the job's external-authorizer profile, so this is a [[#Profile used for running ECF requests|backward compatibility]] issue.<br />
<br />
==Debugger updates==<br />
<br />
===SoftSpy authorization===<br />
<p><br />
SoftSpy and Muse are now authorized using the standard zap AUTH mechanism.</p><br />
<p><br />
EDIT CONFIG is no longer used to enter authorization keys, and the second (key entry) screen of SPY EDIT CONFIG no longer appears.</p><br />
<br />
===SoftSpy Error message for DBCSENV===<br />
<p><br />
As in previous releases, SoftSpy is not supported in a DBCS (double-byte character set) environment. As of version 7.7, if the CCAIN parameter DBCSENV is set to a non-zero value, the SPY command is rejected with the following message:</p> <br />
<p class="code">Message 207: SoftSpy may not be used in a DBCS environment.</p><br />
<br />
===Debugger Client version information display on mainframe===<br />
As of version 7.7 and Client build 64, the <var class="product">Janus/TN3270 Debugger</var> Client sends its build and tag number to the mainframe, and this information is displayed in message [[MSIR.1077]]:<br />
<p class="code" style="font-size:93%">MSIR.1077: Begin debug session, user 3, client: Build: 64, Tag: 2 (Janus debugger session)</p><br />
<br />
This information is not sent if the Debugger Client build number is less than 64, and the mainframe side views all Client versions prior to build 64 as build 63.<br />
<br />
The build number, which identifies Client versions, is displayed in the Client <b>Audit Trail</b> tab at start up:<br />
<p class="code">2016 07 30 17:21:47 The Rocket Software Debugger Client<br />
2016 07 30 17:21:47 Build: 65 (01 August 2016) Tag: 1 GA<br />
</p><br />
<br />
You can also view the build number of the Client at any time by selecting <b>Help > About</b>. And as of Client build 65, the build number is displayed by the Client function <var>&&buildNumber()</var>.<br />
<br />
===Enforcing use of a minimum version of the Debugger Client===<br />
Normally, when you use the TN3270 or Janus Debugger, no restrictions are placed on which version of the Debugger workstation client is used. <br />
As of Client build 65 and Model&nbsp;204 7.7, you can force Clients to have at least a minimum build number in order to invoke a debugging session with your Online. The new Model&nbsp;204 system parameter <var>[[MINDEBCL parameter|MINDEBCL]]</var> sets such a minimum.<br />
<br />
If you set <var>MINDEBCL</var> to a positive value, use a version of the Debugger Client whose build number is less than <var>MINDEBCL</var>, and invoke a debugging session, the debugging session is rejected. An error message is shown in your browser and at the Client, calling for a Client upgrade.<br />
<br />
You also see the following error on the Online's Audit Trail (and on the terminal if you are using <code>TN3270 DEBUG ON</code>):<br />
<p class="code" style="font-size:94%">MSIR.1079: Debugger Client Build: ''xx'' < MINDEBCL: ''yy'' debugger client connection refused <br />
</p><br />
<br />
==Compatibility issues==<br />
<br />
===APSYPAGE parameter cannot be non-zero===<br />
<p>(Applies to the IBM z/OS system.)</p><br />
The <var>APSYPAGE</var> parameter was disabled (but still allowed) in version 7.6. As of version 7.7, if <var>APSYPAGE</var> is non-zero, the Online will not come up and the following error message will appear: <br />
<br />
<p class="code">M204.2958: APSYPAGE is obsolete as of 7.6. <br />
Rocket recommends using RESPAGE and/or TEMPPAGE as the alternative</p> <br />
<br />
See [[APSYPAGE parameter]] for information about alternatives to <var>APSYPAGE</var>.<br />
<br />
===Unlabeled FDV statement compilation errors===<br />
Version 7.7 introduces an edge case incompatibility by disallowing code which is very questionable or clearly wrong; that is, previously the compiler allowed pretty much any statements between the label and the FDV. Such statements are no longer allowed. <br />
<br />
For example, the following was allowed in older versions of Model 204:<br />
<p class="code">a: audit 'About to FDV'<br />
fdv foo<br />
b: frv in a</p><br />
<br />
Inserting SOUL code between a label and an FDV statement is no longer allowed, and so the result of the above is:<br />
<br />
<p class="code">M204.0311 Unacceptable statement reference</p><br />
<br />
This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model 204.<br />
<br />
===KOMM addressing changes===<br />
<ul><br />
<li>KU is no longer 4K addressable from KOMM. It has been relocated to KOMM+1100 and must be addressed using grande (‘G’) instructions.</li><br />
<li>KHEOC has been renamed to KGEOC.</li> <br />
<li>KUUSRNO has been renamed to KBUSRNO.</li> <br />
<li>In addition, all KUP… fields have been removed and replaced by their 64-bit equivalent KUG… fields. <br /><br />
For example, before 7.7, VTBL might be addressed by using <code>L R1,KUPVT</code>. <br /><br />
As of version 7.7, that reference would require <code>LG R1,KUGVT</code>.</li> <br />
</ul> <br />
<br />
For context, see [[Customizing functions and translation tables#Converting user-written functions|Converting user-written functions]].<br />
<br />
===JANUS WEB ON -- "M substitution===<br />
In the command for a <var>JANUS WEB ON</var> rule, <code>"M</code> can now be used to specify a method name. <br />
This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>. See [[#ON rules .28method name substitution.29|JANUS WEB ON rules (method name substitution)]] for details.<br />
<br />
===Journal format compatibility===<br />
A recovery code error unintentionally allowed recovery to be run using Model&nbsp;204 7.6 against a version 7.5 journal, and vice versa. Although the error was benign because the journal formats were the same in those versions, mixing of journal versions and Model&nbsp;204 versions is no longer allowed.<br />
<br />
===Profile used for running ECF requests===<br />
As [[#ecfprofile|described earlier]], the default external-authorizer (ACF2, RACF, or Top/Secret) profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile. <br />
<br />
The default behavior can be changed by turning on the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit.<br />
===$ListNew cannot be used in Initial clause===<br />
<var>$ListNew</var> cannot be used in the <var>Initial</var> clause of a [[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].<br />
<p>This change was introduced as zap maintenance in versions 7.5, 7.6, and 7.7 of Model 204.</p><br />
<br />
==Notes for system manager and installer==<br />
===CRAM SVC installation is deprecated===<br />
The CRAM SVC installation has been deprecated as of version 7.5. <br />Installation of CRAM-XDM is described as part of the [[Model 204 installation]].<br />
===Authorization and maintenance zaps===<br />
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.<br />
<br />
==New and updated messages==<br />
<br />
See [[New and updated messages in Model 204 version 7.7|New and updated messages in Model 204 version 7.7]] for details.<br />
<br />
[[Category: Release notes|Model 204 version 7.7]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=PemToString_(Stringlist_function)&diff=116785PemToString (Stringlist function)2018-09-06T15:16:18Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:PemToString subtitle}}<br />
The PEM (Privacy Enhanced Mail) protocol uses base64 encoding for binary data that needs to be transferred and stored as text.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:PemToString syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>Longstring</var> or <var>String</var> to contain the decoded binary data in the method object, <var class="term">sl</var>.</td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains base64 encoded data.</td></tr><br />
<br />
<tr><th>label</th><br />
<td>The string that identifies the base64 encoded data you want to convert. Examples include <code>X509 CERTIFICATE</code>, <code>X509 CRL</code>, <code>RSA PRIVATE KEY</code>. X509 certificate, private key, and CRL data will be contained within the text markers <code>-----BEGIN <i>label</i>-----</code> and <code>-----END <i>label</i>-----</code>.<br />
<p><br />
This is a required, case-sensitive, value. If it does not match the first and last items of a block of data within <var class="term">sl</var>, no data is returned to <var class="term">%string</var>. </p></td></tr><br />
<br />
<tr><th><var>Occurrence</var></th><br />
<td>The occurrence number within <var class="term">sl</var> of data labeled with <var class="term">label</var>.</td></tr><br />
</table><br />
<br />
===Exceptions===<br />
<var>PemToString</var> can throw the following [[Exceptions|exception]]:<br />
<dl><br />
<dt><var>[[InvalidPemData class|InvalidPemData]]</var><br />
<dd>If the method encounters non-PEM-conforming data, properties of the exception object may indicate the line and position of the error.<br />
</dl><br />
<br />
==Usage notes==<br />
<ul><br />
<li><var>PemToString</var> converts the labeled and structured X509 base64 data you identify. To convert individual base64 strings, you can use the <var>[[StringToBase64 (String function)|StringToBase64 ]]</var> method. <br />
</ul><br />
<br />
==Examples==<br />
The following request loads <var>Longstring</var> <code>%ls</code> with the contents of the base64 encoded CRL (Certificate Revocation List) contained in <var>Stringlist</var> <code>%sl</code>:<br />
<p class="code">b <br />
%ls is longstring <br />
%sl is object stringlist <br />
<br />
[[Text and Html statements#toOption|text to]] %sl = new raw <br />
-----BEGIN X509 CRL----- <br />
MIIBODCB4zANBgkqhkiG9w0BAQQFADBgMQswCQYDVQQGEwJBVTEMMAoGA1UECBMD<br />
UUxEMRkwFwYDVQQKExBNaW5jb20gUHR5LiBMdGQuMQswCQYDVQQLEwJDUzEbMBkG<br />
A1UEAxMSU1NMZWF5IGRlbW8gc2VydmVyFw0wMTAxMTUxNjI2NTdaFw0wMTAyMTQx<br />
NjI2NTdaMFIwEgIBARcNOTUxMDA5MjMzMjA1WjASAgEDFw05NTEyMDEwMTAwMDBa<br />
MBMCAhI0Fw0wMTAxMTUxNjE5NDdaMBMCAhI1Fw0wMTAxMTUxNjIzNDZaMA0GCSqG<br />
SIb3DQEBBAUAA0EAHPjQ3M93QOj8Ufi+jZM7Y78TfAzG4jJn/E6MYBPFVQFYo/Gp<br />
UZexfjSVo5CIyySOtYscz8oO7avwBxTiMpDEQg== <br />
-----END X509 CRL----- <br />
end text <br />
<br />
%ls = %sl:pemToString('X509 CRL') <br />
end <br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]<br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]<br />
</ul><br />
<br />
{{Template:Stringlist:PemToString footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=CheckCertificateRequest_(Stringlist_function)&diff=116784CheckCertificateRequest (Stringlist function)2018-09-06T15:15:53Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:CheckCertificateRequest subtitle}}<br />
This method checks an SSL certificate request against a private key.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:CheckCertificateRequest syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|"Return codes"]]. </td></tr><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains the certificate request to be checked.</td></tr><br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a <var>Stringlist</var> object that contains an RSA-generated private key.</td></tr><br />
<tr><th><var>Password</var></th><br />
<td>This optional, name allowed, parameter is a string that contains a password to decrypt the private key, if necessary.</td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>1</th><td>Keys don't match.</td></tr><br />
<br />
<tr><th>0</th><td>Keys match.</td></tr><br />
<br />
<tr><th>-1</th><td>Private key encrypted but no password provided.</td></tr><br />
<br />
<tr><th>-2</th><td>Private key password invalid.</td></tr><br />
<br />
<tr><th>-4</th><td>Certificate invalid.</td></tr><br />
<br />
<tr><th>-5</th><td>Certificate <var>Stringlist</var> identifier missing (request cancellation).</td></tr><br />
<br />
<tr><th>-6</th><td>Certificate <var>Stringlist</var> identifier invalid (request cancellation).</td></tr><br />
<br />
<tr><th>-7</th><td>Insufficient storage (request cancellation).</td></tr><br />
<br />
<tr><th>-9</th><td>Private key invalid.</td></tr><br />
<br />
<tr><th>-10</th><td>Key <var>Stringlist</var> identifier missing (request cancellation).</td></tr><br />
<br />
<tr><th>-11</th><td>Key <var>Stringlist</var> identifier invalid (request cancellation).</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Examples==<br />
In the following example, the <var>[[CheckCertificateRequest (Stringlist function)|CheckCertificateRequest]]</var> method checks a <var class="product">Janus Security</var>-generated certificate request against its <var class="product">Janus Security</var>-generated private key. <p class="code">...<br />
text to %creq = new raw<br />
&#45;----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIIBzjCCATcCAQAwgY8xDDAKBgNVBAYTA1VTQTELMAkGA1UECBMCTUExEjAQBgNV<br />
BAcTCUNhbWJyaWRnZTEdMBsGA1UEChMUU2lyaXVzIFNvZnR3YXJlIEluYy4xHTAb<br />
BgNVBAsTFFNvZnR3YXJlIERldmVsb3BtZW50MSAwHgYDVQQDExd3d3cuc2lyaXVz<br />
LXNvZnR3YXJlLmNvbTCBnTANBgkqhkiG9w0BAQEFAAOBiwAwgYcCgYEAtR70c/uS<br />
XL/o2pTi9YZnZv8BRLZP95ErHYWR1juQZJc3nCEEduNMAZFIAbrGLm4k2QRZn2+l<br />
qKomoJp/FAYhvH3a0OfmnNfp4csuEXrqr93Vi8Q1UyxlqLMNFRGWjtG2ZpU2rd23<br />
pqfBmSHddlijsK/4zJSGohiGBNiP/EUeCC8CAQOgADANBgkqhkiG9w0BAQQFAAOB<br />
gQCmbEAleV+6G7jAn9xoW5Aprp2TCM/lRiVy7Rc9XRdCy0fauxSdRJcACU1IPVxJ<br />
koU03s4tJiXkg5PkYQKvQwFkJsmTgqHlf5G87NmWZwBeM2VflmqD8UuYHil89o+w<br />
QnWOpiuPMHuIF+A0/zF8S+4nUPoqGn466L4aC2tXweWhjw== <br />
&#45;----END NEW CERTIFICATE REQUEST-----<br />
end text<br />
<br />
text to %pk = new raw <br />
&#45;----BEGIN RSA PRIVATE KEY----- <br />
MIICWgIBAAKBgQC1HvRz+5Jcv+jalOL1hmdm/wFEtk/3kSsdhZHWO5BklzecIQR2<br />
40wBkUgBusYubiTZBFmfb6Woqiagmn8UBiG8fdrQ5+ac1+nhyy4Reuqv3dWLxDVT<br />
LGWosw0VEZaO0bZmlTat3bemp8GZId12WKOwr/jMlIaiGIYE2I/8RR4ILwIBAwKB<br />
gB4v02ip7bof/CRuJdOWZpEqgDYeYqlC3ITrmE5fQrtuiUSwK2kl4gBC4VWfIQe9<br />
BiQrZEU9RkbHBnAZv9irsEnMX1ZgYdntsW5xHe7K1wowBRUrQgAD5SPYRc5b0JEX<br />
PTPL+aJzNaSQNQ/KW3O+QZVN5p3Co2TqjwDzcutQsSkfAkEA+pYxMH2wTCcmabe3<br />
p76qjE2SERSf7nk2yTqw29w1hSYqsj7By51vLWFH/35rMBiqAC5yTgmQjlJIIXw6<br />
kz4ASwJBALkImXUd0PmaJLrCwRIhyDFpeq+UsyaNmtgvjg7W8sEhBRseHV7YXBkh<br />
8mQ6VLMBhtxip7aotArZtwJiPc25ES0CQQCnDst1qSAyxMRGenpv1HGy3mFguGqe<br />
+3nbfHXn6COuGXHMKdaHvkoeQNqqVEd1ZcaqyaGJW7W0NtrA/XxiKVWHAkB7WxD4<br />
votREW3R1ytha9rLm6cfuHdvCRHldQlfOfcra1i8vr4/OugQwUxC0Y3Mq689lxp5<br />
xc1ckSSsQX6JJgtzAkAPAzNsxdsNaAES3L5yqkbux8W2Y2YdjjxZMl1sdPqn9rXN<br />
A8fe68sT76U9rhuJemue1h9jxgq6fscFqZkbNRll <br />
&#45;----END RSA PRIVATE KEY----- <br />
end text <br />
<br />
%rc = %creq:checkCertificaterequest(%pk)<br />
printText {~} is {%rc} <br />
...<br />
</p><br />
<br />
The result is shown below:<br />
<p class="code">%rc is 0 </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:CheckCertificateRequest footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=CheckCertificate_(Stringlist_function)&diff=116783CheckCertificate (Stringlist function)2018-09-06T15:15:29Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:CheckCertificate subtitle}}<br />
This method checks an SSL certificate against a private key.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:CheckCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described elsewhere in [[CheckCertificateRequest (Stringlist function)#Return codes|"Return codes"]].</td></tr><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains the certificate to be checked.</td></tr><br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a <var>Stringlist</var> object that contains an RSA-generated private key.</tr><br />
<tr><th><var>Password</var></th><br />
<td>This optional, name allowed, parameter is a string that contains a password to decrypt the private key, if necessary.</td></tr><br />
</table><br />
<br />
==Examples==<br />
In the following example, the <var>[[CheckCertificate (Stringlist function)|CheckCertificate]]</var> method checks a <var class="product">Janus Security</var>-generated certificate (loaded to <var>Stringlist</var> <code>%cert</code>) against its <var class="product">Janus Security</var>-generated private key (loaded to <var>Stringlist</var> <code>%pk</code>). <p class="code">...<br />
text to %cert = new raw<br />
&#45;----BEGIN X509 CERTIFICATE----- <br />
MIICkTCCAfoCBQHClCdRMA0GCSqGSIb3DQEBBAUAMIGPMQwwCgYDVQQGEwNVU0Ex<br />
CzAJBgNVBAgTAk1BMRIwEAYDVQQHEwlDYW1icmlkZ2UxHTAbBgNVBAoTFFNpcml1<br />
cyBTb2Z0d2FyZSBJbmMuMR0wGwYDVQQLExRTb2Z0d2FyZSBEZXZlbG9wbWVudDEg<br />
MB4GA1UEAxMXd3d3LnNpcml1cy1zb2Z0d2FyZS5jb20wHhcNMTIwNTA4MjM1MjM0<br />
WhcNMzAwODA5MjM1MjM0WjCBjzEMMAoGA1UEBhMDVVNBMQswCQYDVQQIEwJNQTES<br />
MBAGA1UEBxMJQ2FtYnJpZGdlMR0wGwYDVQQKExRTaXJpdXMgU29mdHdhcmUgSW5j<br />
LjEdMBsGA1UECxMUU29mdHdhcmUgRGV2ZWxvcG1lbnQxIDAeBgNVBAMTF3d3dy5z<br />
aXJpdXMtc29mdHdhcmUuY29tMIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQC1<br />
HvRz+5Jcv+jalOL1hmdm/wFEtk/3kSsdhZHWO5BklzecIQR240wBkUgBusYubiTZ<br />
BFmfb6Woqiagmn8UBiG8fdrQ5+ac1+nhyy4Reuqv3dWLxDVTLGWosw0VEZaO0bZm<br />
lTat3bemp8GZId12WKOwr/jMlIaiGIYE2I/8RR4ILwIBAzANBgkqhkiG9w0BAQQF<br />
AAOBgQAtduP6yyMrQTSkJ4v52JlkC1Qhp5yPSLiRi7tXc/sA7i90AY9sUZqBNWWk<br />
XQHP9wjddPlRFtK9bP8slqCwfi2u4Ri8kKGSnTcZY/HQIkEAdEZXHCaykq4j4zde<br />
bSNI0nOLJK7s5vO934+rIrCxjsLSFXmM8BVVE+QlwEQG3dObsg== <br />
&#45;----END X509 CERTIFICATE-----<br />
end text<br />
<br />
text to %pk = new raw <br />
&#45;----BEGIN RSA PRIVATE KEY----- <br />
MIICWgIBAAKBgQC1HvRz+5Jcv+jalOL1hmdm/wFEtk/3kSsdhZHWO5BklzecIQR2<br />
40wBkUgBusYubiTZBFmfb6Woqiagmn8UBiG8fdrQ5+ac1+nhyy4Reuqv3dWLxDVT<br />
LGWosw0VEZaO0bZmlTat3bemp8GZId12WKOwr/jMlIaiGIYE2I/8RR4ILwIBAwKB<br />
gB4v02ip7bof/CRuJdOWZpEqgDYeYqlC3ITrmE5fQrtuiUSwK2kl4gBC4VWfIQe9<br />
BiQrZEU9RkbHBnAZv9irsEnMX1ZgYdntsW5xHe7K1wowBRUrQgAD5SPYRc5b0JEX<br />
PTPL+aJzNaSQNQ/KW3O+QZVN5p3Co2TqjwDzcutQsSkfAkEA+pYxMH2wTCcmabe3<br />
p76qjE2SERSf7nk2yTqw29w1hSYqsj7By51vLWFH/35rMBiqAC5yTgmQjlJIIXw6<br />
kz4ASwJBALkImXUd0PmaJLrCwRIhyDFpeq+UsyaNmtgvjg7W8sEhBRseHV7YXBkh<br />
8mQ6VLMBhtxip7aotArZtwJiPc25ES0CQQCnDst1qSAyxMRGenpv1HGy3mFguGqe<br />
+3nbfHXn6COuGXHMKdaHvkoeQNqqVEd1ZcaqyaGJW7W0NtrA/XxiKVWHAkB7WxD4<br />
votREW3R1ytha9rLm6cfuHdvCRHldQlfOfcra1i8vr4/OugQwUxC0Y3Mq689lxp5<br />
xc1ckSSsQX6JJgtzAkAPAzNsxdsNaAES3L5yqkbux8W2Y2YdjjxZMl1sdPqn9rXN<br />
A8fe68sT76U9rhuJemue1h9jxgq6fscFqZkbNRll <br />
&#45;----END RSA PRIVATE KEY----- <br />
end text <br />
<br />
%rc = %cert:checkCertificaterequest(%pk)<br />
printText {~} is {%rc} <br />
...<br />
</p><br />
<br />
The result is shown below:<br />
<p class="code">%rc is 0 </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:CheckCertificate footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendSignedClientCertificate_(Stringlist_function)&diff=116782AppendSignedClientCertificate (Stringlist function)2018-09-06T15:15:04Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendSignedClientCertificate subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 client certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>. It requires a valid private key, certificate request, and signer. <br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendSignedClientCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described elsewhere in [[AppendSignedCertificate (Stringlist function)#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a string or <var>Stringlist</var> that contains the private key to be used for signing. The key length may be a maximum of 4096 bits (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048.</td></tr><br />
<br />
<tr><th><var>Request</var></th><br />
<td>This name allowed argument is a string or <var>Stringlist</var> that contains the base64 encoded X.509 client certificate request.</td></tr><br />
<br />
<tr><th><var>Signer</var></th><br />
<td>This name allowed argument is a string or <var>Stringlist</var> that contains a base64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> value is used: that is, the certificate will be self-signed. </td></tr><br />
<br />
<tr><th><var>StartDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.</td></tr><br />
<br />
<tr><th><var>EndDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from <var>StartDate</var>. <code>YY</code> may not be less then the current 2-digit year.</td></tr><br />
<br />
<tr><th><var>SerialNumber</var></th><br />
<td>This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount of signing occurrences. </td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).<br />
<p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Example==<br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendSignedClientCertificate footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendSignedCertificate_(Stringlist_function)&diff=116781AppendSignedCertificate (Stringlist function)2018-09-06T15:14:37Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendSignedCertificate subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>. It requires a valid private key and certificate request.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendSignedCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a string or <var>Stringlist</var> that contains the private key to be used for signing. The key length may be a maximum of 4096 bits (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048. </td></tr><br />
<br />
<tr><th><var>Request</var></th><br />
<td>This name allowed argument is a string or <var>Stringlist</var> that contains the base64 encoded X.509 certificate request.</td></tr><br />
<br />
<tr><th><var>Signer</var></th><br />
<td>This optional, name allowed, argument is a string or <var>Stringlist</var> that contains the base64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> value is used: that is, the certificate will be self-signed. </td></tr><br />
<br />
<tr><th><var>StartDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.</td></tr><br />
<br />
<tr><th><var>EndDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from <var>StartDate</var>. <code>YY</code> may not be less then the current 2-digit year.</td></tr><br />
<br />
<tr><th><var>SerialNumber</var></th><br />
<td>This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount<br />
of signing occurrences. </td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).<br />
<p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><br />
<td>All is well.</td></tr><br />
<br />
<tr><th>7</th><br />
<td>Insufficient storage.</td></tr><br />
<br />
<tr><th>10</th><br />
<td>Private key <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>11</th><br />
<td>Invalid private key <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>12</th><br />
<td>Invalid private key <var>Stringlist</var> data (not correctly base64 encoded).</td></tr><br />
<br />
<tr><th>13</th><br />
<td>Certificate request <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>14</th><br />
<td>Invalid certificate request <var>Stringlist</var> identifier.</td></tr> <br />
<br />
<tr><th>15</th><br />
<td>Invalid certificate request.</td></tr> <br />
<br />
<tr><th>16</th><br />
<td>Invalid CA certificate <var>Stringlist</var> identifier.</td></tr> <br />
<br />
<tr><th>17</th><br />
<td>Invalid CA certificate.</td></tr> <br />
<br />
<tr><th>18</th><br />
<td>Invalid start date.</td></tr> <br />
<br />
<tr><th>19</th><br />
<td>Invalid end date.</td></tr> <br />
<br />
<tr><th>20</th><br />
<td>Invalid serial number.</td></tr> <br />
<br />
<tr><th>21</th><br />
<td>Private key does not match signer public key.</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Examples==<br />
This example uses a self-generated private key and certificate request and simply displays the <var>AppendSignedCertificate</var> base64 encoded output.<br />
<p class="code">b<br />
%sl is object stringlist<br />
%ls is longstring<br />
%cr is longstring <br />
%sc is longstring <br />
%rc is float <br />
<br />
%ls = [[GeneratedPrivateKey_(System_function)|%(System):GeneratedPrivateKey]](Length=512)<br />
%cr = %ls:[[CertificateRequest_(String_function)|CertificateRequest]]<br />
<br />
%sl = new <br />
%rc = %sl:appendSignedCertificate(%ls, %cr)<br />
%sl:print <br />
end </p><br />
<p><br />
The result is: </p><br />
<p class="output">&#45;----BEGIN X509 CERTIFICATE-----<br />
MIHvMIGaAgkA3narlNAAAAkwDQYJKoZIhvcNAQELBQAwADAeFw0xNjAzMzAyMDQ3 <br />
MjVaFw0xNjAzMzAyMDQ3MjVaMAAwWjANBgkqhkiG9w0BAQEFAANJADBGAkEAxFfX <br />
HX5yDlQg/Jp/fA2KqZqpuz/N+Ga1vrGs3+RSQ5zjrwjkyg9Ltd8pHgvcvnCt38MV <br />
BqoqWKDOXU/kVRaYCQIBAzANBgkqhkiG9w0BAQsFAANBAG8BPhU1lLQFGGW2TZon <br />
MrzOypC/ztchIxU3CSUFCSRaD6h5N6b6DmLVKnHgbiUPZEDqZ0sSqy6mrOd9yI/2 <br />
zPg= <br />
&#45;----END X509 CERTIFICATE----- <br />
8 </p><br />
<p><br />
You can use the following statements to somewhat "unpack" the base64<br />
result, but the resulting element names are not very meaningful: </p><br />
<p class="code">%sc = %sl:pemToString('X509 CERTIFICATE')<br />
%sc:derToXmlDoc:print <br />
</p><br />
<p><br />
The result is: </p><br />
<p class="output">%sc:derToXmlDoc:print:<br />
<Sequence> <br />
<Sequence> <br />
<Integer>16030188579305029648</Integer> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier> <br />
<Null/> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<UTCTime>20160330214812.000Z</UTCTime> <br />
<UTCTime>20160330214812.000Z</UTCTime> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier><br />
<Null/> <br />
</Sequence> <br />
<BitString bits="576"><br />
304602410085C691E0BCB563 ... BE261FE07892276D227180203F-<br />
5AF8C0199094369020103<br />
</BitString> <br />
</Sequence><br />
</Sequence><br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier><br />
<Null/><br />
</Sequence><br />
<BitString bits="512"><br />
571F364D0665995B6623E475 ... 149C9EA91D2D047F7658E8657A<br />
</BitString> <br />
</Sequence><br />
</p><br />
<p><br />
The <var>DerToXmlDoc</var> method that is used above does not understand the semantics of the standard tags for the signed certificate items. No SOUL method interprets signed certificate items as well as, for example, the <var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> does for a private key. </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendSignedCertificate footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendPrivateKeyInfo_(Stringlist_function)&diff=116780AppendPrivateKeyInfo (Stringlist function)2018-09-06T15:14:02Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendPrivateKeyInfo subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method adds lines from the information section of an SSL private key to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendPrivateKeyInfo syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%number</th><td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object to receive the private key information.</td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains the base64 encoded text of an RSA private key.</td></tr><br />
<br />
<tr><th><var>Password</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name allowed]], parameter is a string that contains a password to decrypt the private key, if necessary.</td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><br />
<td>All is well.</td></tr><br />
<br />
<tr><th>1</th><br />
<td>Encrypted but no password specified.</td></tr><br />
<br />
<tr><th>2</th><br />
<td>Encrypted and wrong password specified.</td></tr><br />
<br />
<tr><th>3</th><br />
<td>Out of CCATEMP.</td></tr><br />
<br />
<tr><th>5</th><br />
<td><var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>6</th><br />
<td>Invalid <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>7</th><br />
<td>Insufficient storage.</td></tr><br />
<br />
<tr><th>10</th><br />
<td>Input <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>11</th><br />
<td>Invalid input <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>12</th><br />
<td>Invalid input <var>Stringlist</var> data (not correctly base-64 encoded).</td></tr><br />
<br />
<tr><th>13</th><br />
<td>Invalid request/certificate (internal structure of certificate is not valid).</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>The updated <var>Stringlist</var> contains an arbitrary amount of <br />
information in an arbitrary order. Each list item <br />
is in ID=value format. These are the possible IDs:<br />
<table class="thJustBold"><br />
<tr><th>S.C</th><br />
<td>Subject country</td></tr> <br />
<br />
<tr><th>S.S</th><br />
<td>Subject state or province </td></tr><br />
<br />
<tr><th>S.L</th><br />
<td>Subject locality - city, town, village, etc. </td></tr> <br />
<br />
<tr><th>S.O</th><br />
<td>Subject organization </td></tr> <br />
<br />
<tr><th>S.OU</th><br />
<td>Subject organization unit </td></tr> <br />
<br />
<tr><th>S.CN</th><br />
<td>Subject common name </td></tr> <br />
<br />
<tr><th>I.C</th><br />
<td>Issuer country </td></tr><br />
<br />
<tr><th>I.S</th><br />
<td>Issuer state or province </td></tr> <br />
<br />
<tr><th>I.L</th><br />
<td>Issuer locality: city, town, village, etc. </td></tr> <br />
<br />
<tr><th>I.O</th><br />
<td>Issuer organization </td></tr> <br />
<br />
<tr><th>I.OU</th><br />
<td>Issuer organization unit </td></tr> <br />
<br />
<tr><th>I.CN</th><br />
<td>Issuer common name </td></tr> <br />
<br />
<tr><th>EFF</th><br />
<td>Effective date in YYMMDDHHMISS format (GMT) </td></tr> <br />
<br />
<tr><th>EXP</th><br />
<td>Expiration date in YYMMDDHHMISS format (GMT) </td></tr> <br />
<br />
<tr><th>ALG</th><br />
<td>Key algorithm - currently always RSA </td></tr> <br />
<br />
<tr><th>N</th><br />
<td>Public modulus in hexadecimal </td></tr> <br />
<br />
<tr><th>E</th><br />
<td>Public exponent in hexadecimal </td></tr> <br />
</table><br />
</li><br />
</ul><br />
<br />
==Examples==<br />
In the following example, a private key is hard-coded into one <var>Stringlist</var>, then the information contained in the private key is extracted via <var>AppendPrivateKeyInfo</var> into another <var>Stringlist</var>:<br />
<p class="code">b<br />
<br />
%sl is object stringlist<br />
%pkey is object stringlist<br />
%sl = new<br />
%pkey = new<br />
<br />
text to %pkey raw<br />
&#45;---BEGIN RSA PRIVATE KEY-----<br />
MIIEogIBAAKCAQEAm6TwmSXt4+lyrhwy9SBq2LVjdTeJ5kUbU9jzmBCfw/NuC1tX<br />
YAAdc0UG5DDJYPHkWkYa7+z50SYzmoxKI8PfCLyxSOPeVW9CEhRSyiIIlyjQikIK<br />
a0YMeOXVetGiutl/y346yQYltkbQXb1SOogTg07fTRs7NWcQ4Rrcd6DEnSkrHxbv<br />
T04Z0MwoSojA+NRyBCMpa+w+R0dzrBNZIT11WOccecYjEyuPSS2ydcdgr/Rp4WKC<br />
UHmRulXWQjhEjwqFPRG4f8BkYJGr8lN262M4ti4Z11KV/lYA/lEpYUkmCaY936p4<br />
IoVoQy8GFn7mj50sxwSa446bTvKlVPsySMDK2wIBAwKCAQAZ8NLEMPz7UZMdBLMo<br />
...<br />
aQmxZUwUo7em8Ci6dX17AoGAcmpQ5AUj5vMdRnOmiIhLM+jgbbQjBD+52hwbkkIn<br />
sZ00cQ5asvdrHt3ziIqN7RMu5okuwdFTdk5IGHTA43qykel0e7wxwADI7qybJXWF<br />
rsIve5XyKCD55gAM4W8y4+CLkCv6dPwmkTq4vfdaYr0/NPIvigzUq0NEXFVPJfQc<br />
GncCgYEAlFIEKq0mVWLBtZRwNjehKOaWGkVVHJnoWqlBngfamQkOiGvWScQ0MVbw<br />
K3U00KpuNHRF5RVy035uoU2tnQDLyG+RmUO7j2+t90MOmgXqiZlTz08uf/fQaprd<br />
NzpmjANA/9cT3rwHD31LsjaDXASM5IW0q7h+vhvVLtVkDzDnW5w= <br />
&#45;----END RSA PRIVATE KEY-----<br />
end text<br />
<br />
%sl:appendPrivateKeyInfo(%pkey)<br />
%sl:print <br />
end<br />
</p><br />
The result is something like:<br />
<p class="output">ALG=RSA <br />
N=9BA4F09925EDE3E972AE1C32F5206AD8 ... A461AEFECF9D126339A8C4A23C3DF08B-<br />
CB148E3DE556F42121452CA22089728D08 ... 4D1B3B356710E11ADC77A0C49D292B1F-<br />
16EF4F4E19D0CC284A88C0F8D472042329 ... 2507991BA55D64238448F0A853D11B87-<br />
FC0646091ABF25376EB6338B62E19D7529 ... E38E9B4EF2A554FB3248C0CADB<br />
E=03<br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendPrivateKeyInfo footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendPemData_(Stringlist_subroutine)&diff=116779AppendPemData (Stringlist subroutine)2018-09-06T15:13:32Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendPemData subtitle}}<br />
The PEM (Privacy Enhanced Mail) protocol uses base64 encoding for binary data that needs to be transferred and stored as text. <var>AppendPemData</var> lets you store PEM data as a series of base64 encoded <var>[[Stringlist class|Stringlist]]</var> items within beginning and ending text marker items.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendPemData syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains labeled, base64 encoded data.</td></tr><br />
<br />
<tr><th><var>Data</var></th><br />
<td>The <var>Longstring</var> or <var>String</var> you are appending to the data stored in <var class="term">sl</var>. </td></tr><br />
<br />
<tr><th><var>label</var></th><br />
<td>The string that identifies the base64 encoded data you are appending. The data is stored as a series of <var class="term">sl</var> items contained within items that are the text markers <code>-----BEGIN <i>label</i>-----</code> and <code>-----END <i>label</i>-----</code>.<br />
<p><br />
This is a required, case-sensitive, value. </p></td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>The appended data is retrievable with the <var>[[PemToString (Stringlist function)|PemToString]]</var> method.<br />
</ul><br />
<br />
==Examples==<br />
<p class="code">b<br />
%ls is longstring<br />
%sl is object stringlist<br />
%ls = 'My PEM content' <br />
%sl:Appendpemdata(%ls, 'SSL SESSION PARAMETERS')<br />
printtext {~} = {%sl:print}<br />
end<br />
</p><br />
<p><br />
The result is: </p><br />
<p class="output"><nowiki>%sl:print = -----BEGIN SSL SESSION PARAMETERS-----<br />
1KhA18XUQIOWlaOFlaM=<br />
-----END SSL SESSION PARAMETERS-----<br />
</nowiki></p><br />
If you were to apply the <var>Base64toString</var> method to the string within the begin and end markers in the preceding result, that is:<br />
<p class="code">printtext {~} = {'1KhA18XUQIOWlaOFlaM=':base64tostring}<br />
</p><br />
The result is:<br />
<p class="output">'1KhA18XUQIOWlaOFlaM=':base64tostring = My PEM content </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]<br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]<br />
</ul><br />
<br />
{{Template:Stringlist:AppendPemData footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendGeneratedPrivateKey_(Stringlist_subroutine)&diff=116778AppendGeneratedPrivateKey (Stringlist subroutine)2018-09-06T15:13:00Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendGeneratedPrivateKey subtitle}}<br />
==Syntax==<br />
{{Template:Stringlist:AppendGeneratedPrivateKey syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object to contain the generated private key.</td></tr><br />
<br />
<tr><th><var>Length</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name allowed]], parameter specifies the number of bits in the private key. The value must be at least 64 and no greater than 4096 (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048. The default is 512. <br />
<p class="note"><b>Note:</b> While AppendGeneratedPrivateKey can generate keys whose length is less than 512, such keys are of purely academic interest. To use a key in a certificate request (see <var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var>, for example, requires a key whose length is 512 or greater. </p></td></tr><br />
<br />
<tr><th><var>Exponent</var></th><br />
<td>This optional, name allowed, parameter specifies the number of bits in the public exponent (E). This must be either 3 or X'10001'. The default is 3. </td></tr><br />
<br />
<tr><th><var>Salt</var></th><br />
<td>This optional, name allowed, parameter is a string that contains seed data for a random number generator. </td></tr><br />
</table><br />
<br />
==Examples==<br />
In the following example, a private key is generated into a <var>Stringlist</var> and displayed in base64 format, then the private key is extracted to a binary string, loaded into an <var>XmlDoc</var>, and printed:<br />
<p class="code">b<br />
<br />
%sl is object stringlist<br />
%ls is longstring<br />
%sl = new<br />
<br />
%sl:appendGeneratedPrivateKey(Length=1024)<br />
%sl:print <br />
<br />
%ls = %sl:pemToString('RSA PRIVATE KEY') <br />
%ls:RSAPRIVATEKEYTOXMLDOC:print <br />
end<br />
</p><br />
The result is something like:<br />
<p class="output">&#45;----BEGIN RSA PRIVATE KEY----- <br />
MIICWwIBAAKBgQCPcaITVcyiT2zx4aKymt9u+NEZ4FzbPvlhbBQs+WkYhbErBeOb<br />
FR2e5dmch7h5anX5xG6OneIzJ95ylMMmyWiTAjH5nEH1zI7P3k34/3QjN7YgN+f4<br />
R+z7SHraInHc4QoN6uujWVfCvv1aA6YLjONz72JHrWxLgFZiHHLWSA3Z1wIBAwKB<br />
gBfoRa3johsNPNL68HMZz+fUItmlZM81KZA8rgd+5tlrnYcrpe8uL5p7pETBSWmR<br />
vlRLZ8JvpbMxT73DddvMPBhAdsTRWPg3Ef0vFd/+W2icZ4B1qSlVsy7FIHBzxULX<br />
4DHCgNEPa0YM9vD4pTv7Y4EQSoi1PhQk/8S8O7vDFsFHAkEAxSKHX3wu6EyExpFg<br />
y1MSDyaro9Tm+/Coy72znEsO9IkikE3YsoQeS/ohqMVn1U9o4pp0zktEVh2m5XOn<br />
GcuyhQJBALpG1VSv9ZnWW/05WD38nX4icdIcGUnJOd36g8+HPN0/wMuY5EpQACU5<br />
kocBO9M/BKsInp+sjkw6Hs2YyJu5n6sCQQCDbFo/qB9FiFiEYOsyN2Ffbx0X40Sn<br />
9cXdKSJoMgn4W2xgM+XMWBQypsEbLkU435tBvE3e3Ng5aRnuTRoRMncDAkB8Lzjj<br />
H/kROZKo0OV+qGj+waE2vWYxMNE+pwKKWiiTf9XdEJgxiqrDe7cEq303f1hyBb8V<br />
HbQy0WneZdsSe7/HAkEAj7yu1YIx+78xRa2zI494/QCzTcocC3S1tm1VjI6yLChE<br />
6XRE80rGrU5xtiaqYnABdS1uPQAyyRzcDh1swvnDwQ== <br />
&#45;----END RSA PRIVATE KEY----- <br />
<RSAPrivateKey><br />
<version>0</version><br />
<modulus>100729717618318585848486 ... 070347486493510338730901-<br />
817890230060500171831435 ... 947861190265885563641189-<br />
612871869577433527035045 ... 102393395848393488456151</modulus><br />
<publicExponent>3</publicExponent><br />
<privateExponent>167882862697197643080811 ... 203586267839124774891838-<br />
978848363631503834341669 ... 3621646783354544762317395-<br />
123358365246652607958565 ... 784368917835086686503239</privateExponent><br />
<prime1>103247913368407610232689 ... 170858989455376441749390-<br />
58859505943349295342502743592645253</prime1><br />
<primes>975610202008600046064537 ... 272137236445431323153153-<br />
9829343947046884546335129776791467</primes><br />
<exponent1>688319422456050734884593 ... 361139059929702509611662-<br />
6039239670628899530228335162395096835</exponent1><br />
<exponent2>650406801339066697376358 ... 890181424824296954215435-<br />
4359886229298031256364223419851194311</exponent2><br />
<coefficient>7528119772196662607878768 ... 656935021038455079267606-<br />
303026918447360800362338060867429057473</coefficient><br />
</RSAPrivateKey><br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendGeneratedPrivateKey footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendEncryptedSecurityData_(Stringlist_subroutine)&diff=116777AppendEncryptedSecurityData (Stringlist subroutine)2018-09-06T15:12:33Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendEncryptedSecurityData subtitle}}<br />
This subroutine RC4-encrypts a <var>Stringlist</var> that contains a base64 encoded, SSL-certificate related item (certificate request, certificate, private key, etc.).<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendEncryptedSecurityData syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object to contain the encrypted, base64 data.</td></tr><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object that contains unencrypted, base64 data.</td></tr><br />
<br />
<tr><th><var>Password</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a string that contains a password (encryption key) to seed the RC4 algorithm. This value must be at least five characters long. </td></tr><br />
<br />
<tr><th><var>Identifier</var></th><br />
<td>This optional, name allowed, parameter is a string that is part of a data-identifying text at the beginning and end of the base64 data to be encrypted. The text is in the form <code>-----BEGIN <i>string</i>-----</code> and <code>-----END <i>string</i>-----</code>, where the default for <var class="term">string</var> is <code>RSA PRIVATE KEY</code>. Some other <var class="term">string</var> replacements, for example, include <code>X509 CERTIFICATE</code>, and <code>X509 CRL</code>. <br />
<p><br />
This is a case-sensitive, value; if it does not match the first and last items of data within <var class="term">sl</var>, no data is returned to the method object, <var class="term">sl</var>. </p> </td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>The length of the encrypted data matches the length of the unencrypted data.<br />
</ul><br />
<br />
==Examples==<br />
In the following example, the <code>%creq</code> <var>Stringlist</var> is loaded with a base64 encoded SSL certificate request, which is then RC4-encrypted and added to <var>Stringlist</var> <code>%sl</code> by the <var>AppendEncryptedSecurityData</var> method. The encrypted contents are then printed: <p class="code">...<br />
text to %creq = new raw<br />
&#45;----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIIBSDCB8wIBADCBjzEMMAoGA1UEBhMDVVNBMQswCQYDVQQIEwJNQTESMBAGA1UE<br />
BxMJQ2FtYnJpZGdlMR0wGwYDVQQKExRTaXJpdXMgU29mdHdhcmUgSW5jLjEdMBsG<br />
A1UECxMUU29mdHdhcmUgRGV2ZWxvcG1lbnQxIDAeBgNVBAMTF3d3dy5zaXJpdXMt<br />
c29mdHdhcmUuY29tMFowDQYJKoZIhvcNAQEBBQADSQAwRgJBAMIofDUItsJLIREb<br />
8UJ93Xm3sJRkYI9qus6lPj76iGOLoQEExSVMved24YxtBlC84IPQrl1+foNcFYSv<br />
OAnfA0ECAQOgADANBgkqhkiG9w0BAQQFAANBAFY6cU6+8p2E9xejVNACmQx2quSV<br />
rudOnjS3jGeKl4Ga/wqg3Yrvg5BwMAWxGn1reh7DhX9j/ScjuBWVIgBkU9M=<br />
&#45;----END NEW CERTIFICATE REQUEST-----<br />
end text <br />
<br />
%sl:APPENDENCRYPTEDSECURITYDATA(%creq, Password='12345', Identifier='NEW CERTIFICATE REQUEST')<br />
%sl:print<br />
...<br />
</p><br />
<br />
The result is shown below:<br />
<p class="code">&#45;----BEGIN NEW CERTIFICATE REQUEST----- <br />
mzU3hcc5C0PhBbRWKhFeysu/SEn1oNSuv8tldCRTgQGSSx/9WQIarg9Q60gYqoVP<br />
lNivlNniqBLnw69pf4bdsg+Nhb+t2SBImuQ6Ar9eCMqNQa1Lfa0IAf/akuIqDdMa<br />
8N5aIIwTIlDuy0P4agbLZg1tG5oUKTbfcCgEibAfNm+qKazxV0G39s4SGFW+Turf<br />
68byY3fPD1kumMAPJBUCgvLf5iI+ayOSH5K6hQJtCAInXmG+DnqHfnUgS9F80Jcb<br />
/BzgIFktn/GV1POVX5VXZxQWDFzYXIVZJkyflsLdl1qWuAeXmwEHZRXy9yIxDc0R<br />
zTxxOmI18406SojaHK7HUN9UcCrlT1BWsbBsuD81eWw7FpAImI/z3sAfqg37cEgp<br />
Df75M4koUrT8wD6SHSx9ezII0GPaiAr1EUTzATRSoq6hoWS/TrpvE2STOyI= <br />
&#45;----END NEW CERTIFICATE REQUEST-----<br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendEncryptedSecurityData footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendCertificateRequestInfo_(Stringlist_function)&diff=116776AppendCertificateRequestInfo (Stringlist function)2018-09-06T15:11:54Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendCertificateRequestInfo subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method adds lines from the information portion of an SSL certificate to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendCertificateRequestInfo syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described elsewhere in [[AppendCertificateInfo (Stringlist function)#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<br />
<tr><th>certificateRequest</th><br />
<td>A <var>Stringlist</var> object that contains the raw text of an SSL certificate request.</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>The updated <var>Stringlist</var> contains an arbitrary amount of <br />
information in an arbitrary order. Each list item <br />
is in "ID=value" format. These are the possible IDs:<br />
<table class="thJustBold"><br />
<tr><th>S.C</th><td>Subject country</td></tr> <br />
<tr><th>S.S<td>Subject state or province </td></tr> <br />
<tr><th>S.L<td>Subject locality - city, town, village, etc. </td></tr> <br />
<tr><th>S.O<td>Subject organization </td></tr> <br />
<tr><th>S.OU<td>Subject organization unit </td></tr> <br />
<tr><th>S.CN<td>Subject common name </td></tr> <br />
<tr><th>I.C<td>Issuer country </td></tr> <br />
<tr><th>I.S<td>Issuer state or province </td></tr> <br />
<tr><th>I.L<td>Issuer locality - city, town, village, etc. </td></tr> <br />
<tr><th>I.O<td>Issuer organization </td></tr> <br />
<tr><th>I.OU<td>Issuer organization unit </td></tr> <br />
<tr><th>I.CN<td>Issuer common name </td></tr> <br />
<tr><th>EFF<td>Effective date in YYMMDDHHMISS format (GMT) </td></tr> <br />
<tr><th>EXP<td>Expiration date in YYMMDDHHMISS format (GMT) </td></tr> <br />
<tr><th>ALG<td>Key algorithm - currently always RSA </td></tr> <br />
<tr><th>N<td>Public modulus in hexadecimal </td></tr> <br />
<tr><th>E<td>Public exponent in hexadecimal </td></tr> <br />
</table><br />
</ul><br />
<br />
==Examples==<br />
In the following example, a certificate request is hard-coded into one <var>Stringlist</var>, then the information contained in the certificate is translated via <var>AppendCertificateInfo</var> into another <var>Stringlist</var>:<br />
<p class="code">b<br />
%sl is object stringlist<br />
%creq is object stringlist<br />
<br />
%sl = new<br />
%creq = new<br />
<br />
text to %creq raw<br />
&#45;----BEGIN NEW CERTIFICATE REQUEST----- <br />
MIIBSTCB9AIBADCBkzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMRIwEAYDVQQH <br />
EwlDYW1icmlkZ2UxHTAbBgNVBAoTFFNpcml1cyBTb2Z0d2FyZSBJbmMuMR0wGwYD <br />
VQQLExRTb2Z0d2FyZSBEZXZlbG9wbWVudDElMCMGA1UEAxMcd3d3LnNpcml1cy1z <br />
b2Z0d2FyZS5jb206NDQ0NDBZMA0GCSqGSIb3DQEBAQUAA0gAMEUCQGeK7FoF5KOV <br />
fkJeY+/mGFB/mnqOK+lXtKkyGsvE2IT3sWe6bt4/UBxAmryflxa1xnRirTBcvyr2 <br />
092HW5Cie90CAQMwDQYJKoZIhvcNAQEEBQADQQAfh/JQALxnQo9YFczgpSbLlN6i <br />
UKSS4qVe1e2resil+rSmrG+W9YTBIDnT2GcdotAIF9L3/6LQdmuipXgicg3m <br />
&#45;----END NEW CERTIFICATE REQUEST----- <br />
end text<br />
<br />
%sl:appendCertificateInfo(%creq)<br />
%sl:print<br />
end<br />
</p><br />
The result is something like:<br />
<p class="output">S.C=US <br />
S.S=MA <br />
S.L=Cambridge <br />
S.O=Sirius Software Inc.<br />
S.OU=Software Development <br />
S.CN=www.sirius-software.com:4444 <br />
ALG=RSA <br />
N=678AEC5A05E4A3957E425E63EFE618507F9A7A8E ... 305CBF2AF6D3DD875B90A27BDD<br />
E=03 <br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendCertificateRequestInfo footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendCertificateRequest_(Stringlist_function)&diff=116775AppendCertificateRequest (Stringlist function)2018-09-06T15:11:22Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendCertificateRequest subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method generates an SSL certificate request from a given private key, and it adds the certificate request lines to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendCertificateRequest syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object to contain the generated request.</td></tr><br />
<br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a string or <var>Stringlist</var> that contains an RSA-generated private key. This key must be greater than or equal to 512 and less than or equal to 4096 (as of version 7.7 of Model&nbsp;204). The pre-7.7 maximum is 2048 bits. </td></tr><br />
<br />
<tr><th><var>Country</var></th><br />
<td>This name allowed, optional, string argument inserts a country value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>State</var></th><br />
<td>This name allowed, optional, string argument inserts a state/province value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>City</var></th><br />
<td>This name allowed, optional, string argument inserts a locality value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>Organization</var></th><br />
<td>This name allowed, optional, string argument inserts an organization value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>OrganizationalUnit</var></th><br />
<td>This name allowed, optional, string argument inserts an organization unit (OU) value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>CommonName</var></th><br />
<td>This name allowed, optional, string argument inserts a common-name (CN) value into the generated certificate request.</td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model&nbsp;204 7.7 and later), and <var>SHA512</var> (Model&nbsp;204 7.7 and later).<br />
<p class="note"><b>Note:</b> Although supported and currently the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><br />
<td>All is well.</td></tr><br />
<br />
<tr><th>7</th><br />
<td>Insufficient storage.</td></tr><br />
<br />
<tr><th>10</th><br />
<td>Private key <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>11</th><br />
<td>Invalid private key <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>12</th><br />
<td>Invalid private key.</td></tr><br />
<br />
<tr><th>13</th><br />
<td>Challenge data mismatch.</td></tr><br />
<br />
<tr><th>14</th><br />
<td>Bad private key/challenge signature.</td></tr><br />
</table><br />
<br />
==Examples==<br />
In the following example, the certificate request that is generated from a private key by <var>AppendCertificateRequest</var> is displayed in base64, then checked by <var>[[CheckCertificateRequest (Stringlist function)|CheckCertificateRequest]]</var>, then converted to string by <var>[[PemToString (Stringlist function)|PemToString]]</var> and loaded to an <var>XmlDoc</var> by <var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>:<br />
<p class="code">b<br />
<br />
%sl is object stringlist<br />
%pk is object stringlist<br />
%rc is float <br />
%ls is longstring <br />
%sl = new<br />
<br />
text to %pk raw<br />
&#45;----BEGIN RSA PRIVATE KEY----- <br />
MIICWgIBAAKBgQC1HvRz+5Jcv+jalOL1hmdm/wFEtk/3kSsdhZHWO5BklzecIQR2<br />
40wBkUgBusYubiTZBFmfb6Woqiagmn8UBiG8fdrQ5+ac1+nhyy4Reuqv3dWLxDVT<br />
LGWosw0VEZaO0bZmlTat3bemp8GZId12WKOwr/jMlIaiGIYE2I/8RR4ILwIBAwKB<br />
gB4v02ip7bof/CRuJdOWZpEqgDYeYqlC3ITrmE5fQrtuiUSwK2kl4gBC4VWfIQe9<br />
BiQrZEU9RkbHBnAZv9irsEnMX1ZgYdntsW5xHe7K1wowBRUrQgAD5SPYRc5b0JEX<br />
PTPL+aJzNaSQNQ/KW3O+QZVN5p3Co2TqjwDzcutQsSkfAkEA+pYxMH2wTCcmabe3<br />
p76qjE2SERSf7nk2yTqw29w1hSYqsj7By51vLWFH/35rMBiqAC5yTgmQjlJIIXw6<br />
kz4ASwJBALkImXUd0PmaJLrCwRIhyDFpeq+UsyaNmtgvjg7W8sEhBRseHV7YXBkh<br />
8mQ6VLMBhtxip7aotArZtwJiPc25ES0CQQCnDst1qSAyxMRGenpv1HGy3mFguGqe<br />
+3nbfHXn6COuGXHMKdaHvkoeQNqqVEd1ZcaqyaGJW7W0NtrA/XxiKVWHAkB7WxD4<br />
votREW3R1ytha9rLm6cfuHdvCRHldQlfOfcra1i8vr4/OugQwUxC0Y3Mq689lxp5<br />
xc1ckSSsQX6JJgtzAkAPAzNsxdsNaAES3L5yqkbux8W2Y2YdjjxZMl1sdPqn9rXN<br />
A8fe68sT76U9rhuJemue1h9jxgq6fscFqZkbNRll <br />
&#45;----END RSA PRIVATE KEY----- <br />
end text<br />
<br />
%rc = %sl:appendCertificaterequest(%pk, country='USA')<br />
print 'return code is ' %rc <br />
%sl:print<br />
<br />
%rc = %sl:CheckCertificateRequest(PrivateKey=%pk)<br />
print 'checkcert return code is ' %rc <br />
<br />
%ls = %sl:pemtostring('NEW CERTIFICATE REQUEST')<br />
%ls:derToXmlDoc:print <br />
end<br />
</p><br />
The result is something like:<br />
<p class="output"><br />
return code is 0 <br />
&#45;----BEGIN NEW CERTIFICATE REQUEST----- <br />
MIIBPTCBpwIBADAAMIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQC1HvRz+5Jc<br />
v+jalOL1hmdm/wFEtk/3kSsdhZHWO5BklzecIQR240wBkUgBusYubiTZBFmfb6Wo<br />
qiagmn8UBiG8fdrQ5+ac1+nhyy4Reuqv3dWLxDVTLGWosw0VEZaO0bZmlTat3bem<br />
p8GZId12WKOwr/jMlIaiGIYE2I/8RR4ILwIBA6AAMA0GCSqGSIb3DQEBBAUAA4GB<br />
ADWssWlvaA55XIg0VezigMSpIumTtRUUGHSA3H3l8f7bo3FLPyWg1dr2MSwJKW09<br />
OmEAPGfQgmxN+LTEkzkjHGkevU0Mlj5MvtnF3ltdVbbJHSY+KW+DrdeRjU/5AiMj<br />
e/43fYThb2ea4JySezVY7AUSls5+4C1yx0V3X1s677lI <br />
&#45;----END NEW CERTIFICATE REQUEST----- <br />
checkcert return code is 0 <br />
<Sequence> <br />
<Sequence> <br />
<Integer>0</Integer><br />
<Sequence/> <br />
<Set> <br />
<Sequence> <br />
<ObjectIdentifier>2.5.4.6</ObjectIdentifier><br />
<PrintableString>USA</PrintableString><br />
</Sequence><br />
</Set> <br />
<Sequence> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier> <Null/> <br />
</Sequence> <br />
<BitString bits="1104"> 30818702818100B51EF473 ... 62E6E24D904599F6-<br />
FA5A8AA26A09A7F1 ... A3B0AFF8CC9486A2-<br />
188604D88FFC451E082F020103<br />
</BitString><br />
</Sequence><br />
<ContextSpecific tag="0"/> <br />
</Sequence> <br />
<Sequence><br />
<ObjectIdentifier>1.2.840.113549.1.1.4</ObjectIdentifier> <br />
<Null/> <br />
</Sequence> <br />
<BitString bits="1024"> 35ACB1696F680E79 ... C4DF8B4C49339231-<br />
C691EBD4D0C963E4 ... 45775F5B3AEFB948 <br />
</BitString><br />
</Sequence> </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendCertificateRequest footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendCertificateInfo_(Stringlist_function)&diff=116774AppendCertificateInfo (Stringlist function)2018-09-06T15:10:53Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendCertificateInfo subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method adds lines from the information section of an SSL certificate to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendCertificateInfo syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|"Return codes"]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<br />
<tr><th>certificate</th><br />
<td>A <var>Stringlist</var> object that contains the raw text of a valid SSL certificate.</td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><td>All is well.</td></tr><br />
<br />
<tr><th>1</th><td>Encrypted but no password specified.</td></tr><br />
<br />
<tr><th>2</th><td>Encrypted and wrong password specified.</td></tr><br />
<br />
<tr><th>3</th><td>Out of CCATEMP.</td></tr><br />
<br />
<tr><th>5</th><td><var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>6</th><td>Invalid <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>7</th><td>Insufficient storage.</td></tr><br />
<br />
<tr><th>10</th><td>Input <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>11</th><td>Invalid input <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>12</th><td>Invalid input <var>Stringlist</var> data (not correctly base-64 encoded).</td></tr><br />
<br />
<tr><th>13</th><td>Invalid request/certificate (internal structure of certificate is not valid).</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>The updated <var>Stringlist</var> contains an arbitrary amount of <br />
information in an arbitrary order. Each list item <br />
is in ID=value format. These are the possible IDs:<br />
<table class="thJustBold"><br />
<tr><th>S.C</th><br />
<td>Subject country</td></tr><br />
<br />
<tr><th>S.S</th><br />
<td>Subject state or province </td></tr> <br />
<br />
<tr><th>S.L</th><br />
<td>Subject locality - city, town, village, etc. </td></tr> <br />
<br />
<tr><th>S.O</th><br />
<td>Subject organization </td></tr> <br />
<br />
<tr><th>S.OU</th><br />
<td>Subject organization unit </td></tr> <br />
<br />
<tr><th>S.CN</th><br />
<td>Subject common name </td></tr> <br />
<br />
<tr><th>I.C</th><br />
<td>Issuer country </td></tr><br />
<br />
<tr><th>I.S</th><br />
<td>Issuer state or province </td></tr> <br />
<br />
<tr><th>I.L</th><br />
<td>Issuer locality - city, town, village, etc. </td></tr><br />
<br />
<tr><th>I.O</th><br />
<td>Issuer organization </td></tr> <br />
<br />
<tr><th>I.OU</th><br />
<td>Issuer organization unit </td></tr> <br />
<br />
<tr><th>I.CN</th><br />
<td>Issuer common name </td></tr> <br />
<br />
<tr><th>EFF</th><br />
<td>Effective date in YYMMDDHHMISS format (GMT) </td></tr> <br />
<br />
<tr><th>EXP</th><br />
<td>Expiration date in YYMMDDHHMISS format (GMT) </td></tr><br />
<br />
<tr><th>ALG</th><br />
<td>Key algorithm - currently always RSA </td></tr> <br />
<br />
<tr><th>N</th><br />
<td>Public modulus in hexadecimal </td></tr> <br />
<br />
<tr><th>E</th><br />
<td>Public exponent in hexadecimal </td></tr> <br />
</table><br />
</li><br />
</ul><br />
<br />
==Examples==<br />
In the following example, a certificate is hard-coded into one <var>Stringlist</var>, then the information contained in the certificate is translated via <var>AppendCertificateInfo</var> into another <var>Stringlist</var>:<br />
<p class="code">b<br />
<br />
%sl is object stringlist<br />
%cert is object stringlist<br />
<br />
%sl = new<br />
%cert = new<br />
<br />
text to %cert raw<br />
-----BEGIN CERTIFICATE-----<br />
MIIB2TCCAUKgAwIBAgIESP4m7jANBgkqhkiG9w0BAQQFADAxMQswCQYDVQQGDAJVUzEMMAoGA1UE<br />
CgwDRE9FMRQwEgYDVQQDDAsqLm55Y2VkLm9yZzAeFw0wODEwMjAxOTAxMDJaFw0xODEwMTkxOTAx<br />
MDJaMDExCzAJBgNVBAYMAlVTMQwwCgYDVQQKDANET0UxFDASBgNVBAMMCyoubnljZWQub3JnMIGf<br />
MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCtdTxPrvwguxIJ9E3+UyzCCRluiyH05cONOUtd1zwv<br />
NgdAQ3EdITqGvWmz1tFWlGmXiADCtCipaJPXjLzUQ5hk0m7yBdM7ScnCh3V+0ls7+fjL/J8pUqvY<br />
BLk5llLePd1qHOak3TPt4NAGMxf2u2Iz47bu0lpfZafCuM8hPHFgYQIDAQABMA0GCSqGSIb3DQEB<br />
BAUAA4GBAF4Ee3T9DSZKVE97Kqzt3lJh/Wwg3i1UI2pc/HC9/rhzLxhTx9xfksAwe1+R5kLkHWyD<br />
ddPfPqErKCdyhZ4QMSkM7bCeSy1aW6iF4R2v00eJ7wECAzO99QUatZ33m6Nwb5PToPDiirgsVWaj<br />
siWpXe998f7KgW0PwTunGmBLQaLg<br />
-----END CERTIFICATE-----<br />
end text<br />
<br />
%sl:appendCertificateInfo(%cert)<br />
%sl:print<br />
<br />
end<br />
</p><br />
The result is something like:<br />
<p class="output"><br />
I.C=US <br />
I.O=ACME <br />
I.CN=*.acme.org <br />
EFF=081020190102 <br />
EXP=181019190102 <br />
S.C=US <br />
S.O=ACME<br />
S.CN=*.acme.org <br />
ALG=RSA <br />
N=AD753C4FAEFC20BB1209F44DFE532CC209196E8B21F4E5C38D394B5DD73C2F36074043711D213- <br />
A86BD69B3D6D1569469978800C2B428A96893D78CBCD4439864D26EF205D33B49C9C287757ED25B- <br />
... <br />
F65A7C2B8CF213C716061 <br />
E=010001 <br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendOpenProcedure footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendClientCertificateRequest_(Stringlist_function)&diff=116773AppendClientCertificateRequest (Stringlist function)2018-09-06T15:10:04Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:Stringlist:AppendClientCertificateRequest subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method generates an SSL client-certificate request from a given client public key, and it adds the request lines to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendClientCertificateRequest syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described elsewhere in [[#Return codes|Return codes]].</td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object to contain the certificate request that is produced.</td></tr><br />
<br />
<tr><th><var>PublicKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a string or <var>Stringlist</var> object that contains an RSA-generated client public key.</td></tr><br />
<br />
<tr><th><var>Country</var></th><br />
<td>This name allowed, optional, string argument inserts a country value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>State</var></th><br />
<td>This name allowed, optional, string argument inserts a state/province value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>City</var></th><br />
<td>This name allowed, optional, string argument inserts a locality value into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>Organization</var></th><br />
<td>This name allowed, optional, string argument inserts an organization value (for example, a company name) into the generated certificate request. </td></tr><br />
<br />
<tr><th><var>OrganizationalUnit</var></th><br />
<td>This name allowed, optional, string argument inserts an organization unit (OU) value into the generated certificate request. For example, a department within a company.</td></tr><br />
<br />
<tr><th><var>CommonName</var></th><br />
<td>This name allowed, optional, string argument inserts a common-name (CN) value into the generated certificate request. For example, a host name like "www.sirius-software.com".</td></tr><br />
<br />
<tr><th><var>Challenge</var></th><br />
<td>This name allowed, optional, string argument inserts the expected authentication challenge data/password. You might need to identify the type of authentication, for example, certificate-based authentication.</td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).<br />
<p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr></table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><td>All is well.</td></tr><br />
<tr><th>3</th><td>Out of CCATEMP.</td></tr><br />
<tr><th>5</th><td><var>Stringlist</var> identifier missing.</td></tr><br />
<tr><th>6</th><td>Invalid <var>Stringlist</var> identifier.</td></tr><br />
<tr><th>7</th><td>Insufficient storage.</td></tr><br />
<tr><th>10</th><td>Public key <var>Stringlist</var> identifier missing.</td></tr><br />
<tr><th>11</th><td>Invalid public key <var>Stringlist</var> identifier.</td></tr><br />
<tr><th>12</th><td>Invalid public key.</td></tr><br />
<tr><th>13</th><td>Challenge data mismatch.</td></tr><br />
<tr><th>14</th><td>Bad public key/challenge signature.</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Examples==<br />
For a closely related example, see the <var>AppendCertificateRequest</var> [[AppendCertificateRequest (Stringlist function)#Examples|Examples]] section.<br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendClientCertificateRequest footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=X509CrlToXmlDoc_(String_function)&diff=116772X509CrlToXmlDoc (String function)2018-09-06T15:09:06Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:X509CrlToXmlDoc subtitle}}<br />
X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation list (CRLs), and more. <var>X509CrlToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a CRL to an <var>[[XmlDoc class|XmlDoc]]</var>. DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.<br />
<br />
==Syntax==<br />
{{Template:String:X509CrlToXmlDoc syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%doc</th><br />
<td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>. </td></tr><br />
<br />
<tr><th>string</th><br />
<td>A DER encoded string that contains the contents of a CRL (Certificate Revocation List). </td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Prior to version 7.7 of Model&nbsp;204, input to this method that created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters produced an error. As of version 7.7, the lengths of the created text nodes are not restricted. </li><br />
<br />
<li><var>X509CrlToXmlDoc</var> is very similar to <br />
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CrlToXmlDoc</var> understands the semantics of the CRL tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CrlToXmlDoc</var> [[X509CrlToXmlDoc (String function)#Examples|example]], below. </li><br />
<br />
<li><var>X509CrlToXmlDoc</var> is a complete implementation of the PKCS standards for CRLs. </li><br />
<br />
<li><var class="product">Janus Web Server</var> is not equipped to use the <var>XmlDoc</var> CRLs automatically; you have to process them yourself. Probably, for efficiency, you want to get the CRL at startup time, then store it somewhere easy to get at (a global <var>[[NamedArraylist class|NamedArraylist]]</var>, for example, or a file, depending on how many certificates are in the list.<br />
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a CRL. </li><br />
</ul><br />
<br />
==Examples==<br />
<ol><br />
<li>[[PemToString (Stringlist function)#Examples|The PemToString example]] loads a <var>Longstring</var> with the contents of the base64 encoded CRL (Certificate Revocation List). If that <var>Longstring</var> is <code>%ls</code> below, the following statement converts that string to the XmlDoc whose contents are printed thereafter:<br />
<p class="code">%ls:x509CrlToXmlDoc:print </p><br />
<br />
The result is shown in part below:<br />
<p class="code"><CertificateList><br />
<tbsCertList><br />
<signature><br />
<algorithm name="md5WithRSAEncryption"><br />
1.2.840.113549.1.1.4<br />
</algorithm><br />
<parameters/><br />
</signature><br />
<issuer><br />
<RelativeDistinguishedName><br />
<countryName>AU</countryName><br />
</RelativeDistinguishedName><br />
<RelativeDistinguishedName><br />
<stateOrProvinceName type="PrintableString"><br />
QLD<br />
</stateOrProvinceName><br />
</RelativeDistinguishedName><br />
...<br />
</issuer><br />
<thisUpdate type="UTCTime"><br />
20010115162657.000Z<br />
</thisUpdate> <br />
<nextUpdate type="UTCTime"><br />
20010214162657.000Z <br />
</nextUpdate><br />
<revokedCertificates> <br />
<revokedCertificate> <br />
<userCertificate>1</userCertificate> <br />
<revocationDate type="UTCTime"> <br />
19951009233205.000Z <br />
</revocationDate><br />
</revokedCertificate><br />
<revokedCertificate><br />
<userCertificate>3</userCertificate><br />
<revocationDate type="UTCTime"> <br />
19951201010000.000Z<br />
</revocationDate><br />
</revokedCertificate> <br />
<revokedCertificate> <br />
<userCertificate>4660</userCertificate> <br />
<revocationDate type="UTCTime"> <br />
20010115161947.000Z<br />
</revocationDate> <br />
</revokedCertificate><br />
...<br />
</revokedCertificates> <br />
</tbsCertList><br />
...<br />
</CertificateList><br />
</p></li><br />
<br />
<li>If you have a web port from which you can get a CRL, you might do something like this: <br />
<p class="code">%httprequest:url = %crlUrl<br />
%httpResponse = %httpRequest:[[Get (HttpRequest function)|Get]]<br />
%doc = %httpResponse:X509CrlToXmlDoc </p><br />
<p class="note">'''Note:''' Janus will not validate a signature on a CRL returned by a <var>Get</var>. </p></li><br />
</ol><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]<br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]<br />
</ul><br />
<br />
{{Template:String:X509CrlToXmlDoc footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=X509CertificateToXmlDoc_(String_function)&diff=116771X509CertificateToXmlDoc (String function)2018-09-06T15:08:26Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:X509CertificateToXmlDoc subtitle}}<br />
X509 is a general authentication framework that establishes standard formats for for public-key certificates, certificate revocation lists (CRLs), and more. <var>X509CertificateToXmlDoc</var> converts a string (<var>Longstring</var>) that contains a certificate to an <var>[[XmlDoc class|XmlDoc]]</var>. DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.<br />
<br />
==Syntax==<br />
{{Template:String:X509CertificateToXmlDoc syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%doc</th><br />
<td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>.</td></tr><br />
<br />
<tr><th>string</th><br />
<td>A DER encoded string that contains the contents of a digital certificate. </td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Prior to version 7.7 of Model&nbsp;204, input to this method that created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters produced an error. As of version 7.7, the lengths of the created text nodes are not restricted. </li><br />
<br />
<li><var>X509CertificateToXmlDoc</var> is very similar to <br />
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>X509CertificateToXmlDoc</var> understands the semantics of the certificate tags, so it provides more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc example]] with the <var>X509CertificateToXmlDoc</var> [[X509CertificateToXmlDoc (String function)#Examples|example]], below. </li><br />
<br />
<li><var>X509CertificateToXmlDoc</var> is a complete implementation of the PKCS standards for X509 certificates. </li><br />
<br />
<li>While <var>X509CertificateToXmlDoc</var> is a complete implementation of the PKCS standard, the <code>&lt;RelativeDistinguishedName&gt;</code> element can contain a wide variety of attributes that <var>X509CertificateToXmlDoc</var> does not understand. Under Model 204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <code>&lt;unknown&gt;</code> elements with an <code>&lt;ObjectIdentifier&gt;</code> element that indicates the ASN.1 object identifier. <br />
<p class="note"><b>Note:</b> You are advised not to use an <code>&lt;unknown&gt;</code> element in your programs, since future updates to the <var>X509CertificateToXmlDoc</var> method may add support for the element, in which case the element name will change to a proper name. If such an element is of interest, [[Contacting Rocket Software Technical Support|contact Rocket Software technical support]]. </p></li><br />
<br />
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a certificate.<br />
</ul><br />
<br />
==Examples==<br />
<ol><br />
<li>In the following example, the <var>[[PemToString (Stringlist function)|PemToString]]</var> method loads <var>Longstring</var> <code>%ls</code> with the contents of a base64 encoded Certificate. The <var>Longstring</var> is then converted to an <var>XmlDoc</var> whose contents are printed: <p class="code"> ...<br />
text to %sl = new raw<br />
&#45;----BEGIN X509 CERTIFICATE-----<br />
MIIDyjCCArICBQG6t2wFMA0GCSqGSIb3DQEBBAUAMIGpMQswCQYDVQQGEwJVUzEL<br />
MAkGA1UECBMCTUExEjAQBgNVBAcTCUNhbWJyaWRnZTEdMBsGA1UEChMUU2lyaXVz<br />
IFNvZnR3YXJlIEluYy4xHTAbBgNVBAsTFFNvZnR3YXJlIERldmVsb3BtZW50MTsw<br />
OQYDVQQDEzJzaXJpdXN8c2lyaXVzLXNvZnR3YXJlLmNvbXx3d3cuc2lyaXVzLXNv<br />
...<br />
3YJysceP8RdU9u6KMFca9AaXKIiBhDClAq0jXk/0ew4xlXJM8bRUXEVVWPGjXiP6<br />
owT5jqCxVO6YyYMabVa1+fIu7g2EKOW26+2xdOBoti8wUHV5u/v7EhX4gl1SFRA0<br />
HDqjT/PVYzAkLPr7LrMVUtPaE6ostjP4uLKr5K8IUz/Q7oab+sHeiTGk9qhflTMA<br />
K7EE6AGXgEWr5q18Xc0=<br />
&#45;----END X509 CERTIFICATE-----<br />
end text <br />
<br />
%ls = %sl:pemToString('X509 CERTIFICATE')<br />
%ls:x509certificateToXmldoc:print <br />
... </p><br />
<br />
The result is shown below:<br />
<p class="code"><br />
<Certificate> <br />
<tbsCertificate> <br />
<version>0</version> <br />
<serialNumber>7427550213</serialNumber> <br />
<signature> <br />
<algorithm name="md5WithRSAEncryption"> <br />
1.2.840.113549.1.1.4 <br />
</algorithm> <br />
<parameters/> <br />
</signature> <br />
<issuer> <br />
<RelativeDistinguishedName> <br />
<countryName>US</countryName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
<stateOrProvinceName type="PrintableString"> <br />
MA <br />
</stateOrProvinceName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
<localityName type="PrintableString"> <br />
Cambridge <br />
</localityName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
<organizationName type="PrintableString"> <br />
Sirius Software Inc. <br />
</organizationName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
<organizationalUnitName type="PrintableString"><br />
Software Development <br />
</organizationalUnitName> <br />
</RelativeDistinguishedName> <br />
<commonName type="PrintableString"> <br />
sirius|sirius-software.com|www.sirius-software.com<br />
</commonName> <br />
</RelativeDistinguishedName> <br />
</issuer> <br />
<validity> <br />
<notBefore type="UTCTime"> <br />
20120129174641.000Z <br />
</notBefore> <br />
<notAfter type="UTCTime"> <br />
20130129174641.000Z <br />
</notAfter> <br />
</validity> <br />
<subject> <br />
<RelativeDistinguishedName> <br />
<countryName>US</countryName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
<stateOrProvinceName type="PrintableString"> <br />
MA <br />
</stateOrProvinceName> <br />
</RelativeDistinguishedName> <br />
<RelativeDistinguishedName> <br />
...<br />
</RelativeDistinguishedName> <br />
</subject> <br />
<subjectPublicKeyInfo> <br />
<algorithm> <br />
<algorithm name="rsaEncryption"> <br />
1.2.840.113549.1.1.1<br />
</algorithm><br />
<parameters/><br />
</algorithm><br />
<subjectPublicKey bits="2144"> <br />
308201080282010100AEB80E3AE26B644C90081484D304F327CFD79BE9ACA168 ...<br />
... 1046851C2ED4C04DD9020103 <br />
</subjectPublicKey> <br />
</subjectPublicKeyInfo> <br />
</tbsCertificate> <br />
<signatureAlgorithm> <br />
<algorithm name="md5WithRSAEncryption"> <br />
1.2.840.113549.1.1.4<br />
</algorithm><br />
<parameters/><br />
</signatureAlgorithm> <br />
<signatureValue bits="2048"><br />
0A35414FEEDD883CB4195B1D3F5164E2108A1C3A1CC0C38E3170 ...<br />
... 002BB104E801978045ABE6AD7C5DCD<br />
</signatureValue><br />
</Certificate> </p><br />
<br />
<li>To load a client certificate, you might do the following:<br />
<p class="code">%string = %(System):[[ClientCertificate (System function)|ClientCertificate]](RequestCertificate=true)<br />
%doc = %string:X509CertificateToXmlDoc </p><br />
</ol><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li> <br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"]<br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"]<br />
</ul><br />
<br />
{{Template:String:X509CertificateToXmlDoc footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=RSAPrivateKeyToXmlDoc_(String_function)&diff=116770RSAPrivateKeyToXmlDoc (String function)2018-09-06T15:07:41Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:RSAPrivateKeyToXmlDoc subtitle}}<br />
<var>RSAPrivateKeyToXmlDoc</var> converts a string (<var>Longstring</var>) that contains an RSA-generated private key to an <var>[[XmlDoc class|XmlDoc]]</var>. <br />
DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.<br />
<br />
==Syntax==<br />
{{Template:String:RSAPrivateKeyToXmlDoc syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%doc</th><br />
<td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>.</td></tr><br />
<br />
<tr><th>string</th><br />
<td>A DER encoded string that contains the contents of a digital certificate. </td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Prior to version 7.7 of Model&nbsp;204, input to this method that created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters produced an error. An example of such input is a 4096-bit key (which requires 1024 hex characters). As of version 7.7, the lengths of created text nodes are not restricted. </li><br />
<br />
<li><var>RSAPrivateKeyToXmlDoc</var> is very similar to <br />
<var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, except that <var>RSAPrivateKeyToXmlDoc</var> understands the semantics of the private key tags, so it provides more meaningful XML element names. </li><br />
<br />
<li><var>RSAPrivateKeyToXmlDoc</var> is a complete implementation of the PKCS standards for private key syntax. </li><br />
<br />
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var> nor to validate the signature on a certificate. </li><br />
</ul><br />
<br />
==Examples==<br />
In the following example, the <var>[[PemToString (Stringlist function)|PemToString]]</var> method loads <var>Longstring</var> <code>%ls</code> with the contents of an RSA private key. <var>RSAPrivateKeyToXmlDoc</var> then converts the <var>Longstring</var> to an <var>XmlDoc</var> whose contents are printed: <br />
<p class="code"> ...<br />
text to %sl = new raw<br />
&#45;----BEGIN RSA PRIVATE KEY-----<br />
MIIEogIBAAKCAQEAm6TwmSXt4+lyrhwy9SBq2LVjdTeJ5kUbU9jzmBCfw/NuC1tX<br />
YAAdc0UG5DDJYPHkWkYa7+z50SYzmoxKI8PfCLyxSOPeVW9CEhRSyiIIlyjQikIK<br />
a0YMeOXVetGiutl/y346yQYltkbQXb1SOogTg07fTRs7NWcQ4Rrcd6DEnSkrHxbv<br />
T04Z0MwoSojA+NRyBCMpa+w+R0dzrBNZIT11WOccecYjEyuPSS2ydcdgr/Rp4WKC<br />
UHmRulXWQjhEjwqFPRG4f8BkYJGr8lN262M4ti4Z11KV/lYA/lEpYUkmCaY936p4<br />
IoVoQy8GFn7mj50sxwSa446bTvKlVPsySMDK2wIBAwKCAQAZ8NLEMPz7UZMdBLMo<br />
...<br />
aQmxZUwUo7em8Ci6dX17AoGAcmpQ5AUj5vMdRnOmiIhLM+jgbbQjBD+52hwbkkIn<br />
sZ00cQ5asvdrHt3ziIqN7RMu5okuwdFTdk5IGHTA43qykel0e7wxwADI7qybJXWF<br />
rsIve5XyKCD55gAM4W8y4+CLkCv6dPwmkTq4vfdaYr0/NPIvigzUq0NEXFVPJfQc<br />
GncCgYEAlFIEKq0mVWLBtZRwNjehKOaWGkVVHJnoWqlBngfamQkOiGvWScQ0MVbw<br />
K3U00KpuNHRF5RVy035uoU2tnQDLyG+RmUO7j2+t90MOmgXqiZlTz08uf/fQaprd<br />
NzpmjANA/9cT3rwHD31LsjaDXASM5IW0q7h+vhvVLtVkDzDnW5w= <br />
&#45;----END RSA PRIVATE KEY-----<br />
end text <br />
<br />
%ls = %sl:pemToString('RSA PRIVATE KEY')<br />
%ls:RSAPrivateKeyToXmlDoc:print<br />
... </p><br />
<br />
The abridged result is shown below:<br />
<p class="code"><RSAPrivateKey><br />
<version>0</version><modulus>196482721346 ...<br />
...685825059547</modulus> <br />
<publicExponent>3</publicExponent><br />
<privateExponent>32747120224474 ...<br />
...832238758867</privateExponent><br />
<prime1>163032211406922467 ...<br />
...063864355897</prime1><br />
<primes>120517730607 ...<br />
...628528150451</primes><br />
<exponent1>108688140937 ...<br />
...709242903931</exponent1><br />
<exponent2>803451537383 ...<br />
...419018766967</exponent2><br />
<coefficient>104154110092 ...<br />
...977615354780</coefficient><br />
</RSAPrivateKey> </p><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var></li> <br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"] </li><br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"] </li><br />
</ul><br />
<br />
{{Template:String:RSAPrivateKeyToXmlDoc footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=DerToXmlDoc_(String_function)&diff=116769DerToXmlDoc (String function)2018-09-06T15:06:55Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:DerToXmlDoc subtitle}}<br />
DER (Distinguished Encoding Rules), a subset of BER (Basic Encoding Rules, provide a way to uniquely encode an Abstract Syntax Notation One (ASN.1) type value as a string of eight-bit octets.<br />
<var>DerToXmlDoc</var> converts such a string to a generically-formatted <var>[[XmlDoc class|XmlDoc]]</var>. This generic formatting lets you load and access ASN.1 data from any source, for example, LDAP and SNMP, as well as any X509 certificate-related fields that might not be included in the other more specific [[Release notes for Sirius Mods V8.0#DER2Xml|DER-to-XmlDoc]] methods.<br />
<br />
==Syntax==<br />
{{Template:String:DerToXmlDoc syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%doc</th><br />
<td>An <var>XmlDoc</var> object variable to contain the decoded value of the method object, <var class="term">string</var>. </td></tr><br />
<br />
<tr><th>string</th><br />
<td>A DER encoded string. </td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li><var>DerToXmlDoc</var> does the same work as <var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var>, <var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var>, and<br />
<var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var>, except that those methods understand the semantics of the standard tags for those items, so they provide more meaningful XML element names. Contrast the [[DerToXmlDoc (String function)#Examples|DerToXmlDoc examples]] below with the examples for those more specific methods in their respective "Examples" sections.<br />
<p class="note"><b>Note:</b> Prior to version 7.7 of Model&nbsp;204, input to these four <var class="term">xxx</var><var>ToXmlDoc</var> methods that created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters produced an error. As of version 7.7, the lengths of the created text nodes are not restricted. </p></li><br />
<br />
<li>Currently, no method is available to produce a DER stream from an <var>XmlDoc</var>. </li><br />
</ul><br />
<br />
==Examples==<br />
<ol><br />
<li>[[PemToString (Stringlist function)#Examples|The PemToString example]] loads a <var>Longstring</var> with the contents of the base64 encoded CRL (Certificate Revocation List). If that <var>Longstring</var> is <code>%ls</code> below, the following statement converts that string to the XmlDoc whose contents are printed thereafter:<br />
<p class="code">%ls:derToXmlDoc:print </p><br />
<br />
The result is shown in part below:<br />
<p class="code"><Sequence><br />
<Sequence><br />
<Sequence><br />
<ObjectIdentifier>1.2.840.113549.1.1.4</ObjectIdentifier><br />
<Null/><br />
</Sequence><br />
<Sequence><br />
... <br />
<Set> <br />
<Sequence><br />
<ObjectIdentifier>2.5.4.8</ObjectIdentifier><br />
<PrintableString>QLD</PrintableString> <br />
</Sequence><br />
</Set><br />
... <br />
<UTCTime>20010115162657.000Z</UTCTime><br />
<UTCTime>20010214162657.000Z</UTCTime><br />
<Sequence><br />
<Sequence> <br />
<Integer>1</Integer> <br />
<UTCTime>19951009233205.000Z</UTCTime> <br />
</Sequence> <br />
<Sequence><br />
<Integer>3</Integer> <br />
<UTCTime>19951201010000.000Z</UTCTime><br />
</Sequence> <br />
... </p><br />
<br />
The ellipses indicate snipped content and are not part of the XmlDoc.</li><br />
<br />
<li>In [[RSAPrivateKeyToXmlDoc (String function)#Examples|the RSAPrivateKeyToXmlDoc example]], the <var>PemToString</var> method loads a <var>Longstring</var> with the contents of an RSA private key. If that <var>Longstring</var> is also <code>%ls</code> below, the following statement converts that string to the <var>XmlDoc</var> whose contents are printed below. Compare the XML tags in these results with the tags produced by <var>RSAPrivateKeyToXmlDoc</var>:<br />
<p class="code">%ls:derToXmlDoc:print </p><br />
<br />
The result is shown in part below:<br />
<p class="code"><Sequence><br />
<Integer>0</Integer><br />
<Integer>196482721346 ...<br />
...685825059547</Integer><br />
<Integer>3</Integer><br />
<Integer>327471202244 ...<br />
...832238758867</Integer><br />
<Integer>163032211406 ...<br />
...063864355897</Integer><br />
<Integer>120517730607 ...<br />
...628528150451</Integer><br />
<Integer>108688140937 ...<br />
...709242903931</Integer><br />
<Integer>803451537383 ...<br />
...419018766967</Integer><br />
<Integer>104154110092 ...<br />
...977615354780</Integer> <br />
</Sequence> </p></li><br />
</ol><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var></li> <br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
Background information:<br />
<ul><br />
<li>[http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One "Abstract Syntax Notation One"] </li><br />
<br />
<li>[http://luca.ntop.org/Teaching/Appunti/asn1.html "A Layman's Guide to a Subset of ASN.1, BER, and DER"] </li><br />
</ul><br />
<br />
{{Template:String:DerToXmlDoc footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=SignedCertificate_(String_function)&diff=116768SignedCertificate (String function)2018-09-06T15:06:22Z<p>JAL: /* See also */ add method bto list</p>
<hr />
<div>{{Template:String:SignedCertificate subtitle}}<br />
This method generates a signed SSL certificate from a given certificate request and private key. It adds the lines of the signed certificate to the end of the object certificate-request.<br />
<br />
==Syntax==<br />
{{Template:String:SignedCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%signedCert</th><br />
<td>A <var>String</var> or <var>Longstring</var> to contain the signed certificate that the method creates.</td></tr><br />
<br />
<tr><th>string</th><br />
<td>A <var>String</var> or <var>Longstring</var> that contains a base64 encoded X.509 certificate request.</td></tr><br />
<br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a <var>String</var> or <var>Longstring</var> that contains the RSA-generated private key used to create the signature. This value must be less than or equal to 4096 (as of version 7.7 of Model&nbsp;204). The pre-7.7 maximum is 2048 bits.</td></tr><br />
<br />
<tr><th><var>Signer</var></th><br />
<td>This optional, name allowed, argument is a string that contains a base64 encoded CA (certifying authority) X.509 certificate. If not specified, the method object <var class="term">string</var> is used, and the certificate is self-signed. </td></tr><br />
<br />
<tr><th><var>StartDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.</td></tr><br />
<br />
<tr><th><var>EndDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from <var>StartDate</var>. <code>YY</code> may not be less then the current 2-digit year.</td></tr><br />
<br />
<tr><th><var>SerialNumber</var></th><br />
<td>This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount<br />
of signing occurrences.</td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).<br />
<p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Example==<br />
This example uses a self-generated private key and certificate request and then prints a view of the <var>SignedCertificate</var> output. <br />
The <var>DerToXmlDoc</var> method that is used to "unpack" the content does not understand the semantics of the standard tags for the signed certificate items, so the output tags are somewhat generic. No SOUL method interprets signed certificate items as well as, for example, the <var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> does for a private key. <br />
<p class="code">b<br />
%ls is longstring<br />
%cr is longstring <br />
%sc is longstring <br />
<br />
%ls = %(System):[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]](Length=512)<br />
%cr = %ls:[[CertificateRequest (String function)|CertificateRequest]]<br />
<br />
%sc = %cr:SignedCertificate(%ls)<br />
%sc:derToXmlDoc:print <br />
end </p><br />
<p><br />
The result is: </p><br />
<p class="output">%sc:derToXmlDoc:print:<br />
<Sequence> <br />
<Sequence> <br />
<Integer>16030188579305029649</Integer> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier> <br />
<Null/> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<UTCTime>20160330222419.000Z</UTCTime><br />
<UTCTime>20160330222419.000Z</UTCTime> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier><br />
<Null/> <br />
</Sequence> <br />
<BitString bits="576"><br />
304602410082FCF711CB0B1C ... 06B82C686516711F8769127D0D-<br />
BE318606B7529E5020103<br />
</BitString> <br />
</Sequence><br />
</Sequence><br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier><br />
<Null/><br />
</Sequence><br />
<BitString bits="512"><br />
5D076DA8C002B5077047EA27 ... 5C9CEBB9ED37CF1A0096B47220<br />
</BitString> <br />
</Sequence><br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:String:SignedCertificate footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=ClientCertificateRequest_(String_function)&diff=116767ClientCertificateRequest (String function)2018-09-06T15:05:50Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:ClientCertificateRequest subtitle}}<br />
This page is [[under construction]].<br />
<br />
==Syntax==<br />
{{Template:String:ClientCertificateRequest syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%certRequest</th><br />
<td>A <var>String</var> or <var>Longstring</var> to contain the generated signed certificate request.</td></tr><br />
<br />
<tr><th>string</th><br />
<td>A <var>String</var> or <var>Longstring</var> that contains an RSA-generated client public key. This value must be less than or equal to 4096 (as of version 7.7 of Model&nbsp;204). The pre-7.7 maximum is 2048 bits.</td></tr><br />
<br />
<tr><th><var>Country</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], string argument inserts a country value into the generated client certificate request. </td></tr><br />
<br />
<tr><th><var>State</var></th><br />
<td>This optional, name required, string argument inserts a state/province value into the generated client certificate request. </td></tr><br />
<br />
<tr><th><var>City</var></th><br />
<td>This optional, name required, string argument inserts a locality value into the generated client certificate request. </td></tr><br />
<br />
<tr><th><var>Organization</var></th><br />
<td>This optional, name required, string argument inserts an organization value into the generated client certificate request. </td></tr><br />
<br />
<tr><th><var>OrganizationalUnit</var></th><br />
<td>This optional, name required, string argument inserts an organization unit (OU) value into the generated client certificate request. </td></tr><br />
<br />
<tr><th><var>CommonName</var></th><br />
<td>This optional, name required, string argument inserts a common-name (CN) value into the generated client certificate request.<br />
<p></p></td></tr><br />
<br />
<tr><th><var>Challenge</var></th><br />
<td>This optional, name required, string argument contains expected challenge data.</td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, name required, argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later).<br />
<p class="note"><b>Note:</b> Although supported and currently the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<br />
==Examples==<br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:String:ClientCertificateRequest footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=CertificateRequest_(String_function)&diff=116766CertificateRequest (String function)2018-09-06T15:05:10Z<p>JAL: /* See also */ add method to list</p>
<hr />
<div>{{Template:String:CertificateRequest subtitle}}<br />
This method generates a string that contains an SSL certificate request from an object string that contains a private key. <br />
<br />
==Syntax==<br />
{{Template:String:CertificateRequest syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%certRequest</th><br />
<td>A <var>String</var> or <var>Longstring</var> to contain the generated signed certificate request.</td></tr><br />
<br />
<tr><th>string</th><br />
<td>A <var>String</var> or <var>Longstring</var> that contains an RSA-generated private key. This value must be less than or equal to 4096 (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048 bits.</td></tr><br />
<br />
<tr><th><var>Country</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], string argument inserts a country value into the generated certificate request.<br />
<p></p></td></tr><br />
<br />
<tr><th><var>State</var></th><br />
<td>This optional, name required, string argument inserts a state/province value into the generated certificate request. <br />
<p></p></td></tr><br />
<br />
<tr><th><var>City</var></th><br />
<td>This optional, name required, string argument inserts a locality value into the generated certificate request.<br />
<p></p></td></tr><br />
<br />
<tr><th><var>Organization</var></th><br />
<td>This optional, name required, string argument inserts an organization value into the generated certificate request. <br />
<p></p></td></tr><br />
<br />
<tr><th><var>OrganizationalUnit</var></th><br />
<td>This optional, name required, string argument inserts an organization unit (OU) value into the generated certificate request. <br />
<p></p></td></tr><br />
<br />
<tr><th><var>CommonName</var></th><br />
<td>This optional, name required, string argument inserts a common-name (CN) value into the generated certificate request.<br />
<p></p></td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, name required, argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model&nbsp;204 7.7 and later), and <var>SHA512</var> (Model&nbsp;204 7.7 and later).<br />
<p class="note"><b>Note:</b> Although supported and currently the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Example==<br />
The following request prints a certificate request created from an input private key that is produced by the <var>System</var> method <var>[[GeneratedPrivateKey (System_function)|GeneratedPrivateKey]]</var>:<br />
<p class="code">b<br />
%ls is longstring <br />
%cr is longstring <br />
<br />
%ls = %(System):GeneratedPrivateKey(Length=512) <br />
%cr = %ls:CertificateRequest(Country='USA',state='MA', city='Waltham', Organization='Rocket')<br />
<br />
%cr:derToXmlDoc:print <br />
end<br />
</p><br />
The result is:<br />
<p class="output"><Sequence><br />
<Sequence> <br />
<Integer>0</Integer> <br />
<Sequence> <br />
<Set><br />
<Sequence> <br />
<ObjectIdentifier>2.5.4.6</ObjectIdentifier> <br />
<PrintableString>USA</PrintableString> <br />
</Sequence> <br />
</Set> <br />
<Set> <br />
<Sequence> <br />
<ObjectIdentifier>2.5.4.8</ObjectIdentifier><br />
<PrintableString>MA</PrintableString> <br />
</Sequence> <br />
</Set> <br />
<Set><br />
<Sequence><br />
<ObjectIdentifier>2.5.4.7</ObjectIdentifier><br />
<PrintableString>Waltham</PrintableString> <br />
</Sequence><br />
</Set><br />
<Set><br />
<Sequence> <br />
<ObjectIdentifier>2.5.4.10</ObjectIdentifier><br />
<PrintableString>Rocket</PrintableString> <br />
</Sequence> <br />
</Set> <br />
</Sequence> <br />
<Sequence> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier><br />
<Null/> <br />
</Sequence> <br />
<BitString bits="576"><br />
3046024100A0277685A6EA06E94CF8B ... 0C9E9B07B24FF3D1BB5BBA6F30A9FCF0F-<br />
8F3D80AB2A09EFD020103<br />
</BitString><br />
</Sequence><br />
<ContextSpecific tag="0"/><br />
</Sequence><br />
<Sequence><br />
<ObjectIdentifier>1.2.840.113549.1.1.5</ObjectIdentifier><br />
<Null/><br />
</Sequence><br />
<BitString bits="512"><br />
0B8774C79100F621F6E794BDEBD47BE ... 4C410892A5573F24D25AC32374A571F633<br />
</BitString><br />
</Sequence><br />
</p><br />
<br />
==See also==<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><br />
<li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:String:CertificateRequest footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AppendSignedCertificate_(Stringlist_function)&diff=116765AppendSignedCertificate (Stringlist function)2018-09-06T15:03:34Z<p>JAL: /* See also */ add SignedClientCertificate</p>
<hr />
<div>{{Template:Stringlist:AppendSignedCertificate subtitle}}<br />
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>. It requires a valid private key and certificate request.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendSignedCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|Return codes]]. </td></tr><br />
<br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a string or <var>Stringlist</var> that contains the private key to be used for signing. The key length may be a maximum of 4096 bits (as of version 7.7 of Model 204). The pre-7.7 maximum is 2048. </td></tr><br />
<br />
<tr><th><var>Request</var></th><br />
<td>This name allowed argument is a string or <var>Stringlist</var> that contains the base64 encoded X.509 certificate request.</td></tr><br />
<br />
<tr><th><var>Signer</var></th><br />
<td>This optional, name allowed, argument is a string or <var>Stringlist</var> that contains the base64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> value is used: that is, the certificate will be self-signed. </td></tr><br />
<br />
<tr><th><var>StartDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.</td></tr><br />
<br />
<tr><th><var>EndDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from <var>StartDate</var>. <code>YY</code> may not be less then the current 2-digit year.</td></tr><br />
<br />
<tr><th><var>SerialNumber</var></th><br />
<td>This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount<br />
of signing occurrences. </td></tr><br />
<br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a <var>[[DigestAlgorithm enumeration|DigestAlgorithm]]</var> enumeration value. Valid values are: <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>, <var>SHA384</var> (Model 204 7.7 and later), and <var>SHA512</var> (Model 204 7.7 and later). The default value is <var>SHA256</var> as of Model 204 7.7 (and zap maintenance for versions 7.6 and 7.5).<br />
<p class="note"><b>Note:</b> Although supported and formerly the default, most modern browsers are deprecating <var>SHA1</var>.</p></td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table class="thJustBold"><br />
<tr><th>0</th><br />
<td>All is well.</td></tr><br />
<br />
<tr><th>7</th><br />
<td>Insufficient storage.</td></tr><br />
<br />
<tr><th>10</th><br />
<td>Private key <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>11</th><br />
<td>Invalid private key <var>Stringlist</var> identifier.</td></tr><br />
<br />
<tr><th>12</th><br />
<td>Invalid private key <var>Stringlist</var> data (not correctly base64 encoded).</td></tr><br />
<br />
<tr><th>13</th><br />
<td>Certificate request <var>Stringlist</var> identifier missing.</td></tr><br />
<br />
<tr><th>14</th><br />
<td>Invalid certificate request <var>Stringlist</var> identifier.</td></tr> <br />
<br />
<tr><th>15</th><br />
<td>Invalid certificate request.</td></tr> <br />
<br />
<tr><th>16</th><br />
<td>Invalid CA certificate <var>Stringlist</var> identifier.</td></tr> <br />
<br />
<tr><th>17</th><br />
<td>Invalid CA certificate.</td></tr> <br />
<br />
<tr><th>18</th><br />
<td>Invalid start date.</td></tr> <br />
<br />
<tr><th>19</th><br />
<td>Invalid end date.</td></tr> <br />
<br />
<tr><th>20</th><br />
<td>Invalid serial number.</td></tr> <br />
<br />
<tr><th>21</th><br />
<td>Private key does not match signer public key.</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
For some background information concerning certificates, see [https://en.wikipedia.org/wiki/Public-key_cryptography Public-key cryptography] and [https://en.wikipedia.org/wiki/Certificate_signing_request Certificate signing request].<br />
<br />
==Examples==<br />
This example uses a self-generated private key and certificate request and simply displays the <var>AppendSignedCertificate</var> base64 encoded output.<br />
<p class="code">b<br />
%sl is object stringlist<br />
%ls is longstring<br />
%cr is longstring <br />
%sc is longstring <br />
%rc is float <br />
<br />
%ls = [[GeneratedPrivateKey_(System_function)|%(System):GeneratedPrivateKey]](Length=512)<br />
%cr = %ls:[[CertificateRequest_(String_function)|CertificateRequest]]<br />
<br />
%sl = new <br />
%rc = %sl:appendSignedCertificate(%ls, %cr)<br />
%sl:print <br />
end </p><br />
<p><br />
The result is: </p><br />
<p class="output">&#45;----BEGIN X509 CERTIFICATE-----<br />
MIHvMIGaAgkA3narlNAAAAkwDQYJKoZIhvcNAQELBQAwADAeFw0xNjAzMzAyMDQ3 <br />
MjVaFw0xNjAzMzAyMDQ3MjVaMAAwWjANBgkqhkiG9w0BAQEFAANJADBGAkEAxFfX <br />
HX5yDlQg/Jp/fA2KqZqpuz/N+Ga1vrGs3+RSQ5zjrwjkyg9Ltd8pHgvcvnCt38MV <br />
BqoqWKDOXU/kVRaYCQIBAzANBgkqhkiG9w0BAQsFAANBAG8BPhU1lLQFGGW2TZon <br />
MrzOypC/ztchIxU3CSUFCSRaD6h5N6b6DmLVKnHgbiUPZEDqZ0sSqy6mrOd9yI/2 <br />
zPg= <br />
&#45;----END X509 CERTIFICATE----- <br />
8 </p><br />
<p><br />
You can use the following statements to somewhat "unpack" the base64<br />
result, but the resulting element names are not very meaningful: </p><br />
<p class="code">%sc = %sl:pemToString('X509 CERTIFICATE')<br />
%sc:derToXmlDoc:print <br />
</p><br />
<p><br />
The result is: </p><br />
<p class="output">%sc:derToXmlDoc:print:<br />
<Sequence> <br />
<Sequence> <br />
<Integer>16030188579305029648</Integer> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier> <br />
<Null/> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<UTCTime>20160330214812.000Z</UTCTime> <br />
<UTCTime>20160330214812.000Z</UTCTime> <br />
</Sequence> <br />
<Sequence/> <br />
<Sequence> <br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.1</ObjectIdentifier><br />
<Null/> <br />
</Sequence> <br />
<BitString bits="576"><br />
304602410085C691E0BCB563 ... BE261FE07892276D227180203F-<br />
5AF8C0199094369020103<br />
</BitString> <br />
</Sequence><br />
</Sequence><br />
<Sequence> <br />
<ObjectIdentifier>1.2.840.113549.1.1.11</ObjectIdentifier><br />
<Null/><br />
</Sequence><br />
<BitString bits="512"><br />
571F364D0665995B6623E475 ... 149C9EA91D2D047F7658E8657A<br />
</BitString> <br />
</Sequence><br />
</p><br />
<p><br />
The <var>DerToXmlDoc</var> method that is used above does not understand the semantics of the standard tags for the signed certificate items. No SOUL method interprets signed certificate items as well as, for example, the <var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> does for a private key. </p><br />
<br />
==See also==<br />
<p><br />
<var>Stringlist</var> methods: </p><br />
{{Template:Stringlist crypto methods}}<br />
<p><br />
<var>String</var> methods:</p><br />
<ul><br />
<li><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </li><br />
<br />
<li><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </li><br />
<br />
<li><var>[[SignedClientCertificate (String function)|SignedClientCertificate]]</var> </li><br />
<br />
<li><var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var> </li><br />
<br />
<li><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var></li><br />
<br />
<li><var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var> </li><br />
<br />
<li><var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var> </li><br />
<br />
<li>Multiple cryptographic cipher methods </li><br />
</ul><br />
<p><br />
<var>System</var> methods: </p><br />
<ul><br />
<li><var>[[ClientCertificate (System function)|ClientCertificate]]</var> </li><li><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var> </li><br />
</ul><br />
<p><br />
<var>Socket</var> methods: </p><br />
<ul><br />
<li><var>[[Certificate (Socket function)|Certificate]]</var> </li><br />
</ul><br />
<br />
{{Template:Stringlist:AppendSignedCertificate footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=$Bind&diff=116764$Bind2018-09-06T14:56:45Z<p>JAL: /* Products authorizing {{PAGENAMEE}} */ link repair</p>
<hr />
<div>{{DISPLAYTITLE:$Bind}}<br />
<span class="pageSubtitle">Fast, easy synchronization of system wide resource</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The is no OO equivalent for the $Bind function.</p><br />
<br />
The <var>$Bind</var> function provides a fast and convenient way of synchronizing access to system wide resources. <br />
<br />
<var>$Bind</var> accepts two arguments and returns a numeric code. <br />
<ul><br />
<li>The first argument is the name of the resource to be bound. This resource name can be any string up to 255 bytes long. Only one user can have a resource bound at a time.</li> <br />
<li><br />
The second argument is the number of milliseconds to wait for the resource if it is not immediately available. This argument is available as of <var class="product">[[Sirius Mods]]</var> version 6.9. If it is not specified, <var>$Bind</var> returns immediately, indicating that the resource was not available.</li><br />
</ul><br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = <span class="literal">$Bind</span>(<span class="term">res_name</span>, <span class="term">wait_time</span>)<br />
</p><br />
<br />
<p><br />
<var class="term">%result</var> is set to indicate the success of the function.</p><br />
<br />
===$Bind return codes===<br />
<p class="code">>=0 - User number that currently has resource bound<br />
-1 - Resource name missing<br />
-2 - Insufficient storage to do the bind<br />
-10 - Resource already bound by current user<br />
-20 - Resource successfully bound<br />
</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li>It is the responsibility of each programming team to establish resource naming conventions appropriate to its site. A resource remains bound until it is either explicitly unbound with the [[$Unbind and $UnbindW|$Unbind or $UnbindW]] function or the binding user logs off or is restarted. <br />
</ul><br />
<br />
==Examples==<br />
The following program binds the resource called 'SMITHERS':<br />
<br />
<p class="code">begin<br />
%rc = $Bind('SMITHERS')<br />
end<br />
</p><br />
<br />
The following program binds the resource called 'BURNS', waiting up to 10 seconds (10,000 milliseconds) for the resource to become available.<br />
<p class="code">begin<br />
%rc = $Bind('BURNS', 10000)<br />
end<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[Sirius Functions]]</li><br />
<li>[[Fast/Unload User Language Interface]]</li><br />
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li><br />
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li><br />
<li>[[Janus Sockets]]</li><br />
<li>[[Janus Web Server]]</li><br />
<li>Japanese functions</li><br />
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li><br />
</ul><br />
<br />
[[Category:$Functions|$Bind]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=Storing_security_information_(CCASTAT)&diff=116763Storing security information (CCASTAT)2018-09-04T16:58:13Z<p>JAL: minor formatting</p>
<hr />
<div>==Overview==<br />
<p><br />
CCASTAT is a sequential data set containing a password table of user and file security information in an encrypted format. All <var class="product">Model&nbsp;204</var> security features depend upon the existence of CCASTAT.</p><br />
<p><br />
This page describes how to create and use CCASTAT. </p><br />
<p><br />
For additional information about security and modification of CCASTAT, see [[Establishing and maintaining security]]. </p><br />
<br />
==Creating CCASTAT==<br />
<p><br />
Before you can turn on any security options, you must create a prototype password table using the utility program ZBLDTAB. </p><br />
<br />
<p class="note"><b>Note:</b><br />
When installing external security interfaces with <var class="product">Model&nbsp;204</var>, you must still define a CCASTAT file that contains at least one entry. </p><br />
<br />
===z/OS procedures===<br />
<p><br />
Use the following z/OS JCL to create CCASTAT:</p><br />
<p class="code">//EXEC PGM=ZBLDTAB,REGION=50K<br />
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR<br />
//CCASTAT DD DSN=M204.CCASTAT,UNIT=3330,<br />
// SPACE=(TRK,(2,1)),DISP=(NEW,CATLG),<br />
// DCB=BLKSIZE=13030<br />
</p><br />
<ul><br />
<li>You can specify any direct access unit and any BLKSIZE. If no BLKSIZE is specified, ZBLDTAB assigns a default BLKSIZE of 6302 bytes.</li><br />
<br />
<li>Secondary extents, if defined in the SPACE parameter, will be taken (as needed) as new entries are added and the data set grows. </li><br />
<br />
<li>Each password table entry that does not have terminal security requires 26 bytes. (For more information, see [[Establishing and maintaining security|Terminal security]].)</li><br />
</ul><br />
<br />
===z/VM procedures===<br />
<p><br />
When running under z/VM/CMS, the ZBLDTAB utility program initializes a <var class="product">Model&nbsp;204</var> password table. The format of the ZBLDTAB command is:</p><br />
<p class="syntax">ZBLDTAB [<span class="term">datasetname</span>] [<span class="term">filename filetype</span>] [<span class="term">filemode</span>]<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">datasetname</var> specifies the name of the password table data set on a variable-format disk, with the qualifiers separated by blanks. If the specified disk is variable-format and if no datasetname operand is specified, it is presumed that the name of the password table data set is M204.CCASTAT.</li><br />
<br />
<li><var class="term">filename</var> and <var class="term">filetype</var> signify the name and type of the password table file on a CMS-format disk. </li><br />
</ul><br />
<br />
===z/VSE procedures===<br />
<p><br />
The z/VSE JCL statements required to execute ZBLDTAB are as follows:</p><br />
<p class="code">// JOB ZBLDTAB BUILD MODEL 204 SECURITY FILE<br />
// DLBL M204LIB,'M204.PROD.LIBRARY'<br />
// EXTENT SYSnnn,...<br />
// LIBDEF PHASE,SEARCH=M204LIB.V411<br />
// DLBL CCASTAT,'security file-id',0,SD<br />
// EXTENT SYS001,balance of extent information<br />
// ASSGN SYS001,X'cuu'<br />
// EXEC ZBLDTAB<br />
/*<br />
/&amp;<br />
</p><br />
<ul><br />
<li>The amount of disk storage must be sufficient to contain two <var class="product">Model&nbsp;204</var> pages, 6184 bytes each.</li><br />
<br />
<li>The minimum allocation for FBA devices is 26 blocks. </li><br />
<br />
<li>You must provide the full EXTENT information for the file for the execution of ONLINE or BATCH204, if you are updating the password table with the LOGCTL command.</li><br />
<br />
<li>You must turn on the UPSI switch 3 (<code>SYSOPT=16</code>) to activate <var class="product">Model&nbsp;204</var> security facilities:</li><br />
</ul><br />
<p class="code">UPSI 00010000<br />
</p><br />
<br />
==Using CCASTAT==<br />
<br />
===Data set definitions (z/OS, z/VSE, z/VM)===<br />
<p><br />
Runs that use security options require the following DD statement in their z/OS JCL:</p><br />
<p class="code">//CCASTAT DD DSN=M204.CCASTAT,DISP=SHR<br />
</p><br />
<p><br />
Use the following statements for z/VSE (see z/VSE considerations below):</p><br />
<p class="code">// DLBL CCASTAT,'M204.CCASTAT',0,SD<br />
// EXTENT SYS<i>nnn</i>, (<i>balance of extent info</i>)<br />
// ASSIGN SYS<i>nnn</i>, X'<i>cuu</i>'<br />
</p><br />
<p><br />
z/VM/CMS requires a FILEDEF. For example:</p><br />
<p class="code">FILEDEF CCASTAT G DSN M204 CCASTAT<br />
</p><br />
<p><br />
Encryption prevents security breaches of the password table itself. Decryption occurs when a disk copy of the table is read into main memory. If <var class="product">Model&nbsp;204</var> cannot decrypt the table, it produces a message stating that the password table has been corrupted. </p><br />
<br />
===z/VSE security considerations===<br />
<p><br />
Under z/VSE, the password table is a standard sequential disk file. When a <var>LOGCTL</var> command is entered that requires the CCASTAT data set to be updated, the file is closed for input, opened for output, and written to disk.</p><br />
<p><br />
If the file has not expired, the operating system issues a message indicating that the existing file is going to be overlaid as a result of the operation:</p><br />
<p class="code">EQUAL FILE IN VTOC CCASTAT<br />
</p><br />
<p><br />
To complete the update of the password table, the operator must respond to the message. If a response other than <code>DELETE</code> is given, the operating system attempts to cancel the ONLINE job stream. A message indicating that a STXIT has been trapped is issued.</p><br />
<p><br />
To circumvent the STXIT message and the attendant operator response, you can create the CCASTAT data set with a retention period of zero, as in the DLBL example above. However, the resulting file might be vulnerable to inadvertent erasure by other applications without notice.</p><br />
<p><br />
If CCASTAT is given a zero retention period, use the ALLOCATE utility to allocate two dummy data sets with a retention period of 99/365. Allocate the first data set to immediately precede CCASTAT and allocate the second to immediately follow it.</p><br />
<br />
==Login security==<br />
<p><br />
Login security limits access to <var class="product">Model&nbsp;204</var> by requiring individual users to enter a user ID and a valid password when logging in.</p><br />
<ul><br />
<li>If users are required to log in, every user must enter a valid ID after the <var>LOGIN</var> or <var>LOGON</var> command, followed by a valid password, if one is specified for the user ID. The ID and password are used by <var class="product">Model&nbsp;204</var> to determine authorization to use <var class="product">Model&nbsp;204</var> and the type of operations available to the user.</li><br />
<br />
<li>If users have the option of logging in to the system and a password table is available, user privileges are granted in accordance with the entries in the password table.<br />
<p><br />
The password requirements and restrictions are the same whether a user resets their password at login or it is reset via the <var>LOGCTL</var> command.</p><br />
</li><br />
<br />
<li>If a user does not issue a <var>LOGIN</var> or <var>LOGON</var> command, <var class="product">Model&nbsp;204</var> assumes that the user has superuser privileges. </li><br />
</ul><br />
<br />
===Login implementation===<br />
<p><br />
To implement login security, include the following in the JCL: </p><br />
<ul><br />
<li>Setting of 16 on the <var>[[SYSOPT parameter|SYSOPT]]</var> parameter.</li><br />
<br />
<li>CCASTAT statement in the JCL for the run that points to a previously created password table data set. The discussion of the password table data set starts in [[#Password table data set|Password table data set]], below.</li><br />
<br />
<li>Specification of the number of consecutive times a login can fail (<var>[[LOGTRY parameter|LOGTRY]]</var> parameter) before <var class="product">Model&nbsp;204</var> takes a specified action (<var>[[LOGFAIL parameter|LOGFAIL]]</var> parameter).<br />
<p><br />
Set <var>LOGTRY</var> and <var>LOGFAIL</var> on User 0's parameter line. You can reset <var>LOGTRY</var> during a <var class="product">Model&nbsp;204</var> run.<br />
</p><br />
</li><br />
</ul><br />
<br />
===Login delays===<br />
<p><br />
In addition to the <var>LOGTRY</var> and <var>LOGFAIL</var> parameter options, an additional, automatic security feature is invoked for threads on which users make repeated attempts to login and fail due to invalid ID-password combinations. </p><br />
<p><br />
When login is required, if an invalid user ID and password combination is supplied, an internal count used in the <var>LOGTRY</var> comparison is incremented. On the fourth-failed login attempt, the login process for this thread begins to slow down. The error count is used as the basis for a calculation that increases according to the function <code>N*(N-1)</code>, where <code>N</code> is the number of failed login attempts.</p><br />
<p><br />
A valid user ID and password combination immediately clears the error count and eliminates the delay. During login service delays, <var class="product">Model&nbsp;204</var> also drops the login service priority level from 255 to 0, and marks the offending thread as pending login due to errors.</p><br />
<p><br />
<var>LOGFAIL</var> actions still occur. The user can be bumped by a user with operator or system manager privileges. Even if a bump is performed, the failing error count is not reset until a valid login on that thread occurs. Other <var class="product">Model&nbsp;204</var> users and <var class="product">Model&nbsp;204</var> itself are not affected by the time delay on a failed login, other than the effect that the pending login has by tying up a thread.</p><br />
<p><br />
To monitor the system for unsuccessful logins use the <var>MONITOR</var>, <var>LOGWHO</var>, and <var>STATUS</var> commands. A wait type (WT) of 23 from the <var>MONITOR</var> command indicates that a login for the thread is pending; flags (FLGS) indicate that the user is swappable and bumpable. </p><br />
<br />
===Password table data set===<br />
<p><br />
The password table contains one entry for each user allowed to log in to <var class="product">Model&nbsp;204</var>. Each entry contains the following information:</p><br />
<ul><br />
<li>User ID</li><br />
<br />
<li>Password associated with the ID</li><br />
<br />
<li>Privilege byte (summed), as shown in the following table, indicating the privileges and access rights available to the user after a successful login</li><br />
<br />
<li>Priority setting indicating the priority at which the user is allocated system resources<br />
<table><br />
<caption>Privilege byte settings</caption><br />
<tr class="head"><th>Setting</th><th>Meaning</th></tr><br />
<br />
<tr><td>X'80'</td><td>Superuser privileges. The user can create files (<var>CREATE</var>).</td></tr><br />
<br />
<tr><td>X'40'</td><td>System administrator privileges. The user can issue privileged commands (<var>MONITOR</var>, <var>PRIORITY</var>, <var>WARN</var>, and others).</td></tr><br />
<br />
<tr><td>X'20'</td><td>The user can change the file password when it is used to open a file.</td></tr><br />
<br />
<tr><td>X'10'</td><td>The user can change the login password when logging in to the system.</td></tr><br />
<br />
<tr><td>X'08'</td><td>System manager privileges. The user can issue privileged commands (<var>LOGCTL</var>, <var>DUMPG</var>, <var>IFAMDRAIN</var> and others).</td></tr><br />
<br />
<tr><td>X'04'</td><td>The user can override record security.</td></tr><br />
</table></li><br />
</ul><br />
<p><br />
The password table is stored on disk in an encrypted form to prevent unauthorized users from examining its contents. Password table decryption occurs whenever a disk copy of the table is read into main memory. If <var class="product">Model&nbsp;204</var> cannot decrypt the table, a message is issued stating that the password table is corrupted. </p><br />
<p><br />
Because the information in the password table is in coded form, it is relatively protected from unauthorized access. If more protection is desired, consider IBM utility security on the CCASTAT data set. <var class="product">Model&nbsp;204</var> must be given update privileges for any additional security. </p><br />
<br />
===Password table maintenance===<br />
<p><br />
You can add, delete, or change entries in the password table using the <var>[[LOGCTL command: Modifying file entries in the password table|LOGCTL]]</var> command. The following sections explain how to:</p><br />
<ul><br />
<li>Perform these maintenance functions</li><br />
<br />
<li>Process password table updates</li><br />
<br />
<li>Back up the password table</li><br />
</ul><br />
<p><br />
One of the first maintenance actions is to add a new user ID that includes system manager privileges. Then modify the SUPERKLUGE entry by changing the password and privileges, or by deleting it entirely.</p><br />
<p><br />
Issue the <var>[[LOGLST command|LOGLST]]</var> command to obtain a listing of all login user IDs with associated privileges, but not the passwords.</p><br />
<p><br />
Refer to [[#z/VSE procedures|z/VSE procedures]] for instructions on creating CCASTAT and z/VSE-specific considerations.</p><br />
<br />
===Expanding CCASTAT on disk===<br />
<p><br />
The CCASTAT data set is a simple physical-sequential data set. Therefore, it can be expanded on disk by simply copying the current data set to a larger physical-sequential data set, with the same LRECL, BLKSIZE, and RECFM, using any sequential-data-set-copy utility, such as IBM's IEBGENER. </p><br />
<p><br />
ZBLDTAB or ZCTLTAB cannot be used to expand an existing CCASTAT data set, because those utilities completely re-initialize and rebuild CCASTAT, saving only the single user ID, <code>SUPERKLUGE</code>.<br />
</p><br />
<br />
===Backing up the password table===<br />
<p><br />
Make backup copies of CCASTAT regularly by using an IBM utility or maintaining a card deck that consists of all the <code>LOGCTL A</code> commands executed to date. If you use a card deck, you can reconstruct CCASTAT by running the ZBLDTAB utility and BATCH204. </p><br />
<br />
===Adding entries===<br />
<p><br />
To add new login passwords, user privileges, and priorities for specified user IDs:</p><br />
<ol><br />
<li>Use the <var>[[LOGADD parameter|LOGADD]]</var> parameter on User 0's parameter line to specify the number of slots for new entries to be added to the password table during a run.</li><br />
<br />
<li>Issue the <var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL A]]</var> command.<br />
<p><br />
If the specified user ID is already in the table, or if no slots are available, you receive a message. </p><br />
</li><br />
</ol><br />
<p><br />
By specifying non-numeric user IDs, you can avoid the ambiguity that can result in commands that accept user IDs or user numbers as arguments.</p><br />
<br />
===Deleting entries===<br />
<p><br />
To delete login password table entries, use the <code>LOGCTL D</code> command.</p><br />
<p><br />
If the user ID does not exist in the password table, <var class="product">Model&nbsp;204</var> returns a message stating that the specified entry was not found. If the user ID is found, the password table entry is deleted and the space can be reused for a password table addition during the run. </p><br />
<br />
===Changing entries===<br />
<p><br />
To change login password table entries, use the <code>LOGCTL C</code> command: </p><br />
<ul><br />
<li>The user ID must already exist in the password table. If it does not, <var class="product">Model&nbsp;204</var> issues a message indicating that the entry was not found.</li><br />
<br />
<li>If an entry is omitted, the corresponding entry already in the password table is preserved.</li><br />
<br />
<li>Delimiters are required as place holders if an entry is not changed. For example:<br />
<p class="code">,X'80',NONE Change privileges and priority<br />
,,HIGH Change priority<br />
</p></li><br />
</ul><br />
<br />
===A sample dialogue using LOGCTL===<br />
<p><br />
The following dialogue illustrates the use of LOGCTL in adding, changing, and deleting user IDs:</p><br />
<p class="code">LOGCTL A WASHBURN<br />
<b></b>*** M204.0374: ENTER PASSWORD,PRIVILEGES,PRIORITY<br />
<br />
SESAME,X'80',HIGH<br />
<b></b>*** M204.0379: ENTER TERMINAL LIST,ALL,NONE,ADD,DEL,OR RETURN<br />
<br />
3,4,7,21<br />
<br />
LOGCTL C ABARTH<br />
<b></b>*** M204.0374: ENTER PASSWORD,PRIVILEGES,PRIORITY<br />
<b></b>*** M204.0379: ENTER TERMINAL,ALL,NONE,ADD,DEL,OR RETURN<br />
<br />
LOGCTL D SMITH<br />
</p><br />
<p><br />
Before making any change permanent, <var class="product">Model&nbsp;204</var> displays the new password table entry for an add or change and the old entry for a delete. If the display is interrupted with an ATTENTION, the change is not made. </p><br />
<br />
===Processing login password table updates===<br />
<p><br />
The password table can be updated by concurrently running copies of <var class="product">Model&nbsp;204</var> without preventing a subsequent update to the same table. In order for concurrently running copies of <var class="product">Model&nbsp;204</var> to update the password table, the in-core version of the table must have sufficient core storage allocated to it by the run. The amount of core storage allocated is determined by: </p><br />
<ul><br />
<li>Size of CCASTAT when <var class="product">Model&nbsp;204</var> was initialized </li><br />
<br />
<li>Value of the <var>[[LOGADD parameter|LOGADD]]</var> parameter </li><br />
</ul><br />
<br />
===Updates that exceed allocated storage===<br />
<p><br />
A password table update, by Job A, can increase the number of password entries in the CCASTAT data set on disk. This might make the disk version too large to fit into the virtual storage allocated for the table, during initialization, by a concurrently running job, Job B, that attempts a subsequent update to the table. For example:</p><br />
<ol><br />
<li>Job A and Job B are concurrently running copies of <var class="product">Model&nbsp;204</var> using the same password table data set. Job A has <var>LOGADD</var> set to 7; Job B has it set to 5. </li><br />
<br />
<li>Job A updates the password table, adding six passwords. </li><br />
<br />
<li>Now Job B cannot update CCASTAT because not enough virtual storage was allocated (due to LOGADD=5) to hold the new (after the update by Job A) disk version of CCASTAT (the password table). </li><br />
</ol><br />
<p><br />
In this situation, if the run with insufficient storage attempts to update the password table, it receives these messages:</p><br />
<p class="code"><b></b>*** M204.0312: DISK VERSION OF PASSWORD TABLE TOO LARGE TO READ INTO ALLOCATED STORAGE<br />
<br />
<b></b>*** M204.0343: CHANGE APPLIES ONLY TO THIS RUN; UPDATES TO CCASTAT NOT ALLOWED<br />
</p><br />
<p><br />
To avoid having too little storage allocated for the password table, all jobs that update the same password table should specify the same value for <var>LOGADD</var>. However, if the password table is updated by a job before other jobs that run concurrently are initialized, the problem of insufficient storage can still arise.</p><br />
<p><br />
For example:</p><br />
<ol><br />
<li>Job A initializes with a <var>LOGADD</var> value of 5.</li><br />
<br />
<li>Job A updates the password table, adding three passwords.</li><br />
<br />
<li>Job B, using the same password table, initializes with a <var>LOGADD</var> value<br />
of 5.</li><br />
<br />
<li>Job B updates the password table, adding three passwords.</li><br />
<br />
<li>Job A does not have enough storage even though both jobs specified the same value for <var>LOGADD</var>. Job B initialized after Job A updated the password table and, as a result, Job B was allocated a greater amount of core storage during initialization. </li><br />
</ol><br />
<br />
===Multiple copies of Model 204===<br />
<p><br />
A copy of <var class="product">Model&nbsp;204</var> running concurrently with other copies does not automatically have access to the updates made by the other copies. For example:</p><br />
<ol><br />
<li>Job A and Job B are concurrently running copies of <var class="product">Model&nbsp;204</var> that use the same password table data set.</li><br />
<br />
<li>Job B updates the password table.</li><br />
<br />
<li>Job A does not have access to Job B's updates at this point.</li><br />
<br />
<li>Job A updates the password table. </li><br />
<br />
<li>When Job A updates, <var class="product">Model&nbsp;204</var> reads a current copy of the disk version of the password table into virtual storage. Because this copy was made after Job B's updates, it contains Job B's updates; therefore, Job A has access to Job B's updates. However, Job B does not have access to Job A's updates. Job B must update the password table again to get a current copy of the disk version of the password table data set. </li><br />
</ol><br />
<br />
==Overview of the Password Expiration feature==<br />
<p><br />
The Password Expiration feature enhances the <var class="product">Model&nbsp;204</var> CCASTAT security feature to manage password expiration and includes the changes described in this section. </p><br />
<br />
===Tracking the days a password is valid===<br />
<p><br />
The CCASTAT file saves password expiration and invalid logon count data for each user ID. </p><br />
<ul><br />
<li><var>PWDEXP</var> is a view-only parameter that reflects the number of days a user can login using the same password. The password expires when the period of time elapses since the password was last changed. </li><br />
<br />
<li><var>PWDPURGE</var> is a view-only parameter that reflects the number of days an expired user ID is held in suspension in the CCASTAT file awaiting a new password from the system manager before the user ID is deleted.</li><br />
<br />
<li><var>PWDWARN</var> is a view-only parameter that reflects the number of days prior to password expiration that the user will receive the following warning at login:<br />
<p class="code"><b></b>***M204.2634: YOUR PASSWORD WILL EXPIRE IN n DAYS<br />
</p></li><br />
</ul><br />
<p><br />
For each user login ID requested, the <var>LOGLST</var> command displays:</p><br />
<ul><br />
<li>Password expiration date</li><br />
<br />
<li>Password purge date</li><br />
<br />
<li>The number of unsuccessful login attempts made</li><br />
</ul><br />
<br />
===Revoking passwords and suspending user IDs===<br />
<p><br />
<var class="product">Model&nbsp;204</var> immediately revokes a password after three, sequential, unsuccessful login attempts. A successful login after the first or second failure resets the error counter to zero for that user ID. </p><br />
<p><br />
When a password is revoked, the user ID is held in suspension in the CCASTAT file and cannot login to <var class="product">Model&nbsp;204</var>. The system manager may reinstate that user ID by changing the password before the expiration date and the purge date have passed. </p><br />
<p><br />
When the number of failed login attempts exceeds the number specified by the <var>LOGTRY</var> parameter, the action specified by the <var>LOGFAIL</var> parameter is taken. This is independent of the Password Security feature. If <var>LOGTRY</var> is set to 1 and <var>LOGFAIL</var> is set to 2, for example, the user's thread is deactivated on the second consecutive login attempt, but the user's password is not revoked until after three consecutive failed login attempts.</p><br />
<br />
===Deleting CCASTAT entries===<br />
<p><br />
An entry in CCASTAT is deleted when the password has expired and the grace period specified by the <var>PWDPURGE</var> parameter has elapsed. The system manager must create a new entry for that user ID.</p><br />
<ul><br />
<li>If the Online is running continuously from before midnight till the time a user logs in, the first user to login after midnight triggers the purge of all expired passwords that passed the grace period. A user who logged in before midnight does not trigger the purge; the trigger is a new login after midnight.</li><br />
<br />
<li>If the Online has not been running continuously between midnight and an expired-and-past-the-grace-period user ID attempts to logon, only that user ID is deleted.</li><br />
</ul><br />
<p><br />
Whenever a user ID and password are deleted from the CCASTAT file, the following message is sent to the audit trail:</p><br />
<p class="code"><b></b>*** M204.2636: USER username DELETED FROM PASSWORD TABLE: PASSWORD EXPIRED<br />
</p><br />
<br />
===Defining a password===<br />
<p><br />
A new password must differ from the current and previous password for that user. A password cannot match the value of the corresponding user ID. See [[LOGCTL command: Modifying user ID entries in the password table]].</p><br />
<p><br />
When a password is added or changed, confirmation is requested with the following prompt:</p><br />
<p class="code"><b></b>***M204.2633: RE-ENTER NEW PASSWORD<br />
</p><br />
<p><br />
The system manager can specify passwords that do not expire using the <var>NOEXPIRE</var> keyword in the <var>LOGCTL A</var> and <var>LOGCTL C</var> commands.</p><br />
<br />
===FILE and GROUP passwords===<br />
<p><br />
Password security rules apply to only <var>LOGON</var> passwords.</p><br />
<br />
===Create a backup copy of CCASTAT===<br />
<p><br />
The CCASTAT file used as a testing version should not be your production version. Before testing begins, put a backup copy of your CCASTAT file in a secure place. You and Technical Support might need the unconverted version of your file to diagnose a problem.</p><br />
<br />
===Capturing diagnostic data===<br />
<p><br />
Create a process by which you can capture and deliver debugging materials, such as audit trails, snaps, and dumps to Rocket Software in the event that [[Contacting Rocket Software Technical Support|Technical Support]] needs to help you diagnose problems during testing.</p><br />
<br />
===Increase in CCASTAT===<br />
<p><br />
The Password Expiration feature requires an additional eight bytes per user ID record in the password table. The increase in size is required only for user entries, not file or group entries. You would only have to increase the size of the CCASTAT file, therefore, if the file is almost full or you have a very large number of user entries. The increase might be necessary depending upon the current size of CCASTAT.</p><br />
<br />
==Understanding the ZCTLTAB utility==<br />
<p><br />
The ZCTLTAB utility is a dual purpose job that can be run to read an existing CCASTAT and create a new one pointed to by ddname in JCL NEWSTAT. Also, the ZCTLTAB JCL can be modified, removing the NEWSTAT, and just be used to change values of WARN, PURGE, and/or EXP in an already existing converted CCASTAT.</p><br />
<br />
===Updating CCASTAT using the Password Expiration feature===<br />
<p><br />
When you run the ZCTLTAB utility against the original unconverted CCASTAT file, it creates a copy of the original file and installs the Password Expiration feature into the new file. The new file is no longer compatible with earlier versions of <var class="product">Model&nbsp;204</var>. Therefore, Rocket Software strongly recommends that you save the original unconverted CCASTAT file. Also, use this new CCASTAT file with the Password Expiration feature in testing until you are completely satisfied that it is ready for production work.</p><br />
<p><br />
After you have initially installed the Password Expiration feature in a CCASTAT file, you may run the ZCTLTAB utility against this file to update the password expiration parameters. ZCTLTAB will detect that CCASTAT has already been converted and will not create a new file, but will update the parameters in the existing file. When running with a converted CCASTAT file, the NEWSTAT data set is not required.</p><br />
<p><br />
The first time a job runs with a CCASTAT file converted by ZCTLTAB, the creation date for all existing user IDs are reset to the current date. </p><br />
<p><br />
The Online changes the creation date of a user entry in the CCASTAT file that is enabled for the Password Expiration feature whenever you change the password for that user.</p><br />
<br />
===Setting the security parameters===<br />
<p><br />
The ZCTLTAB utility uses the following input parameters: </p><br />
<ul><br />
<li>EXP to set the number of days until the password expires.</li><br />
<br />
<li>PURGE to set the number of days until an expired password is deleted from CCASTAT.</li><br />
<br />
<li>WARN to set the number of days prior to expiration to start warning the user. </li><br />
</ul><br />
<br />
===Displaying the security parameters===<br />
<p><br />
These values are set within the CCASTAT file. Use the following <var>VIEW</var> command to view the:</p><br />
<ul><br />
<li>EXP value<br />
<p class="code">VIEW PWDEXP<br />
</p></li><br />
<br />
<li>PURGE value<br />
<p class="code">VIEW PWDPURGE<br />
</p></li><br />
<br />
<li>WARN value<br />
<p class="code">VIEW PWDWARN<br />
</p></li><br />
</ul><br />
<br />
===Changing the values of the security parameters===<br />
<p><br />
To change the parameter values, your site simply runs ZCTLTAB with new values for EXP, PURGE, and/or WARN. If you change only one parameter value, the other parameter values remain as they were. Running the ZCTLTAB utility a second time (or more times) does not reset the creation dates of the entries, as the first run did.</p><br />
<br />
===ZCTLTAB condition codes===<br />
<p><br />
The following condition codes are feedback from the ZCTLTAB utility.</p><br />
<table><br />
<tr class="head"><br />
<th>Condition code </th><br />
<th>Meaning</th><br />
</tr><br />
<br />
<tr><br />
<td align="right">0</td><br />
<td>Success</td><br />
</tr><br />
<br />
<tr><br />
<td align="right">4</td><br />
<td>Unable to open a file</td><br />
</tr><br />
<br />
<tr><br />
<td align="right">8</td><br />
<td>Invalid parameters</td><br />
</tr><br />
<br />
<tr><br />
<td align="right">12</td><br />
<td>The version of CCASTAT you used is too old</td><br />
</tr><br />
<br />
<tr><br />
<td align="right">16</td><br />
<td>I/O error occurred when reading or writing a file</td><br />
</tr><br />
<br />
<tr><br />
<td align="right">20</td><br />
<td>Unable to obtain storage (z/VSE only)</td><br />
</tr><br />
</table><br />
<p><br />
No changes are made to the CCASTAT file if the condition code is other than 0.</p><br />
<p><br />
The ZCTLTAB utility writes a message to the CCAOUT data set that explains the condition code or an error. See "ZCTLTAB messages" in the <var class="book">[[Media:M204_MessagesManual_V75.pdf|Rocket Model 204 Messages Manual]]</var>.</p><br />
<br />
===Running ZCTLTAB to update CCASTAT===<br />
<p><br />
The ZCTLTAB utility is unloaded during installation and is used to convert and maintain the CCASTAT file. You can reset the Password Expiration parameters EXP, PURGE, and WARN. This updates your current CCASTAT file and the CCAOUT file to capture the Password Expiration error messages. </p><br />
<br />
====Sample JCL for z/OS ZCTLTAB utility====<br />
<p class="code">//ZCTLTAB JOB (system manager),'system manager ',CLASS=A,MSGCLASS=A<br />
//********************************************************************<br />
//* Job: ZCTLTAB created on: 22 NOV 2009 AT: 16:18:10<br />
//* OPTIONAL Job to create/update CCASTAT with expiration passwords<br />
//* Updates password expiration parameters in CCASTAT<br />
//* 1. Initializes the password expiration feature in CCASTAT if<br />
//* it was not previously converted<br />
//* 2. Changes password expiration parameters in CCASTAT<br />
//* that have already been converted<br />
//* Include the NEWSTAT DD card only when running ZCTLTAB on a<br />
//* CCASTAT file for the first time.<br />
//* Notes:<br />
//* Add jobcard and modify parameters on EXEC card to set days till<br />
//* Expiration, start of Warning messages, and length of grace<br />
//* period before the password is Purged. Change DSNs for<br />
//* LOADLIB and the target CCASTAT. If NEWSTAT is used, modify<br />
//* new data set parameters as needed.<br />
//********************************************************************<br />
//* Notes:<br />
//* May be run to convert and maintain CCASTAT to support<br />
//* expiring passwords. Read Install Guide and job comments<br />
//********************************************************************<br />
//CONVERT PROC SYSINDX='M204',RLSE=V610n,<br />
// DISK=nnnn,VOLSER=nnnnnn<br />
//ZCTLTAB EXEC PGM=ZCTLTAB,PARM='EXP=20,WARN=19,PURGE=255'<br />
//STEPLIB DD DSN=M204.V610n.LOADLIB,<br />
// DISP=SHR<br />
//CCASTAT DD DSN=&amp;SYSINDX..&amp;RLSE..CCASTAT,DISP=SHR<br />
//NEWSTAT DD DSN=&amp;SYSINDX..&amp;RLSE..NEW.CCASTAT,<br />
// DISP=(,CATLG,DELETE),<br />
// SPACE=(TRK,25),<br />
// UNIT=&amp;DISK,<br />
// VOL=SER=&amp;VOLSER<br />
//CCAOUT DD SYSOUT=*<br />
// PEND<br />
//SECURE EXEC CONVERT<br />
//<br />
/* End of ZCTLTAB *******<br />
</p><br />
<br />
====Sample JCL for z/VSE ZCTLTAB utility====<br />
<p class="code">// JOB ZCTLTAB<br />
<b></b>* ********************************************************************<br />
<b></b>* Computer Corporation of America<br />
<b></b>* 6/09<br />
<b></b>* ********************************************************************<br />
<b></b>* ZCTLTAB creates and maintains the converted CCASTAT: (NEW/CCASTAT)*<br />
<b></b>* ********************************************************************<br />
/* Job: ZCTLTAB Created: Sept. 2009 *<br />
/* 1. Creates a new CCASTAT from a standard CCASTAT, copying in *<br />
/* security information and setting initial expiration values.*<br />
/* 2. Changes password expiration parameters in a CCASTAT *<br />
/* that has already been converted. *<br />
/* Include the NEWSTAT DD card only when creating a converted *<br />
/* CCASTAT file. To maintain a converted CCASTAT, remove NEWSTAT.*<br />
/* *******************************************************************<br />
/* Notes: *<br />
/* Add jobcard and modify parameters on EXEC card to set *<br />
/* n_days till Expiration, start of Warning messages, *<br />
/* and length of grace period before the password is Purged. *<br />
/* Change DSNs for LOADLIB and the target CCASTAT. *<br />
/* If NEWSTAT is used, modify new data set parameters as needed. *<br />
/* *<br />
/* ******************************************************************<br />
// EXEC PROC=M204JCL DLBL for JCL sublibrary<br />
// LIBDEF PROC,SEARCH=M204LIB.V610n<br />
// EXEC PROC=M204V610 DLBL for M204 library<br />
// LIBDEF PHASE,SEARCH=M204LIB.V610n<br />
// DLBL CCASTAT,'M204.CCASTAT',99/366,SD<br />
// EXTENT SYSnnn,volser,,,start,length<br />
/* NEWSTAT DLBL required only if creating new converted CCASTAT<br />
/* To update an existing CCASTAT supporting expiring passwords,<br />
/* remove or comment out the NEWSTAT JCL<br />
// DLBL NEWSTAT,'M204.EXPIRE.CCASTAT',99/366,SD<br />
// EXTENT SYSnnn,volser,,,start,length<br />
// EXEC ZCTLTAB,SIZE=AUTO,PARM='EXP=n_days,WARN=n_days,PURGE=n_days'<br />
/*<br />
/&amp;<br />
</p><br />
<br />
====Using ZCTLTAB to modify CCASTAT====<br />
<p><br />
When you run ZCTLTAB to update an already-converted CCASTAT data set, follow the comments in ZCTLTAB to remove references to the <code>NEWSTAT</code> data set.</p><br />
<p class="note"><b>Note:</b> If this data set is not omitted in subsequent execution, an empty reference file may be created.</p><br />
<br />
====Setting EXP, PURGE, and WARN in the ZCTLTAB utility====<br />
<p><br />
The valid values of EXP, PURGE, and WARN are from 0 to 255. </p><br />
<p><br />
In the initial run of the ZCTLTAB utility to convert the CCASTAT file, you must explicitly set the EXP parameter. </p><br />
<p><br />
Setting <code>EXP=0</code> results in the expiration of all passwords in the CCASTAT file, unless they have the NOEXPIRE option. Only user IDs with the NOEXPIRE option will be able to login.</p><br />
<p><br />
Setting <code>EXP=0</code> is valid only if <code>WARN=0</code> is also set or currently exists in a converted CCASTAT.</p><br />
<br />
====Viewing the ZCTLTAB parameters====<br />
<p><br />
If you issue a <var>VIEW</var> command for <var>PWDEXP</var>, <var>PWDPURGE</var>, and <var>PWDWARN</var> and they display a value of -1, CCASTAT has not been converted, and <var class="product">Model&nbsp;204</var> logins behave as they did prior to installing the Password Expiration feature.</p><br />
<br />
==System manager's responsibilities==<br />
<p><br />
In a security emergency, the system manager can change the expiration of all passwords for all jobs accessing a CCASTAT file without bringing those jobs down by running the ZCTLTAB utility. </p><br />
<p><br />
For a running job to read the updated copy of CCASTAT, the job must make a change to CCASTAT in one of the following ways:</p><br />
<ul><br />
<li><code>LOGCTL A</code> command</li><br />
<br />
<li><code>LOGCTL C</code> command</li><br />
<br />
<li>A valid user ID attempts to log in; the user ID is in the password table, but did not enter the correct password.</li><br />
<br />
<li>The job notices that midnight has passed and finds user IDs to delete after a login is attempted. <var class="product">Model&nbsp;204</var> notices when midnight passes and deletes expired passwords when the first user of the day attempts to logon.</li><br />
</ul><br />
<p><br />
<var>PWDEXP</var>, <var>PWDPURGE</var>, and <var>PWDWARN</var> are view-only parameters in Online and Batch204 runs. The only way to change the values is with the ZCTLTAB utility designated by EXP, PURGE, and WARN. Every job that runs with that CCASTAT file from then on will use those values.</p><br />
<br />
<p class="note"><b>Note:</b> Any user who is authorized to submit the ZCTLTAB job can reset the EXP, PURGE, and WARN values. Rocket Software recommends storing this job in a secured data set.</p><br />
<br />
===Supporting password expiration at your site===<br />
<p><br />
The ZCTLTAB utility checks whether the EXP utility parameter is not zero when the WARN utility parameter is not zero. If the EXP parameter is set to zero when WARN is not set to zero, a Return Code of eight (8), meaning invalid parameter, is invoked.</p><br />
<p><br />
CCASTAT may be shared between multiple Online and Batch jobs, as in previous versions.</p><br />
<p><br />
If the ZCTLTAB utility is not run, then the value -1 is displayed for the PWDEXP, PWDPURGE, and PWDWARN parameters, when you issue a VIEW command against them. There is no password expiration and no warning of impending expiration.</p><br />
<br />
===Deleting a user ID===<br />
<p><br />
After a password expires, the password and user ID are deleted from the system when the <var>PWDPURGE</var> number of days has elapsed. The audit trail automatically records deleted user IDs.</p><br />
<p><br />
For Onlines that do not run over midnight, a user whose password has expired past the purge period is deleted from CCASTAT when that user attempts to login. It does not occur when another user logs in.</p><br />
<br />
===Defining passwords===<br />
<p><br />
Follow the instructions for defining passwords listed in [[LOGCTL command: Modifying user ID entries in the password table]].</p><br />
<ul><br />
<li>If you do not run the ZCTLTAB utility, you can apply the lesser restrictions. </li><br />
<br />
<li>After you run the ZCTLTAB utility, you must use the more detailed restrictions.</li><br />
</ul><br />
<br />
===Changing and reusing passwords===<br />
<p><br />
After you run the ZCTLTAB utility, when passwords are changed, they cannot be a repeat of:</p><br />
<ul><br />
<li>The current password</li><br />
<br />
<li>The previous password</li><br />
<br />
<li>The value of <var>[[USERID parameter|USERID]]</var></li><br />
</ul><br />
<br />
====Waiting to change a password====<br />
<p><br />
Users waiting to update CCASTAT with a new password simply wait until CCASTAT is available. The wait type is 23. In previous versions of <var class="product">Model&nbsp;204</var>, when a user was changing a password, then another user attempting to do the same simultaneously received the following message: </p><br />
<p class="code"><b></b>***M204.0370: TABLE IN USE, TRY AGAIN<br />
</p><br />
<p><br />
Now bumpable, swappable waits replace the message. For updating users, the message is eliminated.</p><br />
<br />
===Password from a trusted environment===<br />
<p><br />
No password expiration verification is done for logins from trusted environments, which is the behavior of previous versions of <var class="product">Model&nbsp;204</var>.</p><br />
<br />
===CCASTAT backwards compatibility===<br />
<p><br />
Prior versions of <var class="product">Model&nbsp;204</var> cannot run with the CCASTAT file created for V6R1.0. This backward incompatibility is present when the parameters that control password expiration have been used in a run that has Read-Write access to the CCASTAT file.</p><br />
<p><br />
The system manager should save the original, unconverted CCASTAT file. Once a CCASTAT file is converted for this version, previous versions of <var class="product">Model&nbsp;204</var> can open and look at, but not run with, the converted CCASTAT. Doing so results in the message:</p><br />
<p class="code">M204.0337: Wrong version for CCASTAT - <var class="term">hexVersion</var> </p><br />
<br />
===Managing CCASTAT messages===<br />
<p><br />
When you begin using the Password Expiration feature there is a greater likelihood of CCASTAT enqueue conflicts, because <var class="product">Model&nbsp;204</var> is looking at CCASTAT for more information, so it holds enqueue longer. Also, because of password expirations, CCASTAT is updated more frequently. </p><br />
<p><br />
You might see the following or other messages that reveal enqueue conflicts:</p><br />
<p class="code">M204.0196: Data set <var class="term">datasetName</var> used by <var class="term">ddName</var> DD statement currently in use<br />
<br />
M204.0344: Disk version of CCASTAT changed by job <var class="term">jobName yy.ddd hh:mm</var></p><br />
<br />
[[Category:System management]]<br />
[[Category:Security management]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.2581&diff=116754M204.25812018-08-30T16:01:21Z<p>JAL: add link</p>
<hr />
<div>{{Template:M204.2581 skeleton}}<br />
<br />
<P><br />
The indicated parameter setting, <var class="term">option</var>, is valid only if IOS branch entry (the X'02' bit in the <var>XMEMOPT</var> CCAIN parameter) is being used. And in turn, APF authorization is required if the <var>XMEMOPT</var> X'02' bit is on. </p><br />
<br />
Possible <var class="term">option</var> values are:<br />
<ul><br />
<li><var>[[SYSOPT2 parameter|SYSOPT2]]</var> X'80' bit (XTIOT) <br />
<P><br />
The [[Allocating and directing files dynamically#Extended Task Input.2FOutput Table support|XTIOT]] option might be specified explicitly on a <var>DEFINE</var> or <var>ALLOCATE</var> command or as the default by the <var>SYSOPT2</var> X'80' bit. </p></li><br />
<br />
<li><var>[[NUMBUFG parameter|NUMBUFG]]</var> > 0 <br />
<p><br />
Set as a CCAIN parameter.</P></li><br />
<br />
<li><var>[[NMPSUBZ parameter|NMPSUBZ]]</var> > 0 <br />
<p><br />
Set as a CCAIN parameter.</P></li><br />
</ul><br />
<p><br />
<b>Response:</b> Remove the <var>XTIOT</var> option from the <var>DEFINE</var> or <var>ALLOCATE</var> command, or contact the system manager.</p><br />
<p><br />
<b>System manager response:</b> If the message is issued during initialization, do one of the following:</p><br />
<ul><br />
<li>Remove the X'80' bit from the <var>SYSOPT2</var> parameter (if the complaint is about the XTIOT option)</li><br />
<br />
<li>Set <var>NUMBUFG</var> to 0 (if the complaint is about the <var>NUMBUFG</var> parameter)</li><br />
<br />
<li>Set <var>NMPSUBZ</var> to 0 (if the complaint is about the <var>NMPSUBZ</var> parameter)</li><br />
<br />
<li>Restart Model&nbsp;204 with the <var>XMEMOPT</var> X'02' bit, with [[Cross-memory facilities CRAM and M204XSVC#M204XSVC|M204XSVC]] linked into the Model&nbsp;204 nucleus, and with the load module APF-authorized. </li><br />
</ul><br />
{{Template:M204.2581 footer}}<br />
<!-- skeleton as it was in pdf/XMEMOPT=2 (IOS BRANCH) REQUIRED FOR option/--></div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=SYSOPT2_parameter&diff=116753SYSOPT2 parameter2018-08-30T15:53:30Z<p>JAL: /* Description */ add link</p>
<hr />
<div>{{Template:SYSOPT2 parameter subtitle}}<br />
==Summary==<br />
<dl><br />
<dt>Default value<br />
<dd>0<br />
<dt>Parameter type<br />
<dd>System<br />
<dt>Where set<br />
<dd>On User 0's parameter line; not dynamically resettable<br />
<dt>Related products<br />
<dd>All<br />
<dt>Introduced<br />
<dd><var class="product">Model 204 V6.1</var> or earlier<br />
</dl><br />
<br />
==Description==<br />
<p><br />
The valid settings of <var>SYSOPT2</var> are (options can be summed):</p><br />
<table><br />
<tr class="head"><th>Hex setting </th><th>Decimal setting </th><th>Meaning</th></tr><br />
<br />
<tr><th><var>X'80' </var></th><br />
<td>128 </td><br />
<td>Enable the [[Allocating and directing files dynamically#Extended Task Input.2FOutput Table support|XTIOT]] option.</td></tr><br />
<br />
<tr><th><var>X'40'</var></th><br />
<td> 64 </td><td>The record locking table is allocated above the bar, and 4-byte CCATEMP page numbers are used to address all CCATEMP pages, even those allocated in the small model page pool (page numbers less than 65536). <br />
<p><br />
This requires an increase in <var>[[LRETBL parameter|LRETBL]]</var>. Rocket Software recommends doubling the value of <var>LRETBL</var>.<br />
</p><br />
</td></tr><br />
<br />
<tr><th><var>X'10' </var></th><br />
<td>16</td> <td>Enable [[Performance monitoring and tuning#High Performance FICON (zHPF)|zHPF]] usage. Requires Model&nbsp;204 version 7.6 or later.</td></tr><br />
</table><br />
<p><br />
This parameter applies only to z/OS.</p><br />
<br />
====SYSOPT2=X'80'====<br />
<ul><br />
<li><br />
With <var>SYSOPT2</var> X'80' off, all dynamic allocations default to use the existing <var>TIOT</var> option, unless the <var>XTIOT</var> option is specified on the <var>DEFINE</var> or <var>ALLOCATE</var> command.</li><br />
<li><br />
With <var>SYSOPT2</var> X'80' <i>on</i>, all dynamic allocations that specify the <var>OLD</var> and <var>DIRECT</var> file options use the <var>XTIOT</var> option, unless the <var>TIOT</var> option is specified on the <var>DEFINE</var> or <var>ALLOCATE</var> command. To use this setting, the <var>XMEMOPT</var> X'02' bit must also be set.</li><br />
</ul><br />
<p><br />
With the use of dynamic allocation and the <var>XTIOT</var> option, only the amount of processor storage limits the number of allocated data sets.</p><br />
<br />
====SYSOPT2=X'40'====<br />
<p><br />
Record sets &mdash; found sets, including <var>FDWOL</var> found sets, sorted sets, lists, and LPU lists &mdash; are traced through entries in the record locking table. One entry is required for each segment (49,152 records) in the record set. These entries are CCATEMP page numbers. </p><br />
<p><br />
When the <var>SYSOPT2</var> X'40' bit is set, the entries contain 4-byte CCATEMP page numbers. Setting X'40' provides a substantial increase in the number of simultaneous record sets that can be concurrently active in a given <var class="product">Model&nbsp;204</var> run. Therefore, if you set the X'40' bit, you should also at least double <var>LRETBL</var>. </p><br />
<ul><br />
<li><br />
When the <var>SYSOPT2</var> setting <i>does not</i> include X'40', at any given time the bit maps corresponding to all users holding found sets of any kind must fit into CCATEMP pages designated as the small model page pool, no matter how many pages have been allocated to CCATEMP.</li><br />
<li><br />
When the <var>SYSOPT2</var> setting <i>does</i> include X'40', the CCATEMP page restriction is removed, and user found sets can be placed anywhere within CCATEMP. This includes both the small model page pool and the CCATEMP expansion area, allowing for the possibility of a greater number of concurrent found sets being held by all users.</li><br />
</ul><br />
<br />
====SYSOPT2=X'10'====<br />
This option supports the use of the IBM [[Performance monitoring and tuning#High Performance FICON (zHPF)|High Performance FICON (zHPF)]] interface for faster I/O. Model 204 version 7.6 or later is required. <br />
<br />
[[Category:System parameters]]<br />
[[Category:Parameters]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=AmDaemon_(Daemon_property)&diff=116752AmDaemon (Daemon property)2018-08-27T16:34:21Z<p>JAL: add link</p>
<hr />
<div>{{Template:Daemon:AmDaemon subtitle}}<br />
<br />
<var>AmDaemon</var> returns a <var>[[Boolean enumeration]]</var> to indicate whether <var>AmDaemon</var> was issued on a daemon thread associated with a <var>Daemon</var> object.<br />
<br />
==Syntax==<br />
{{Template:Daemon:AmDaemon syntax}}<br />
<br />
===Syntax terms===<br />
<table><br />
<tr><th>%boolean</th><br />
<td>An enumeration object of type <var>Boolean</var> to contain the returned value of <var>AmDaemon</var>. <var>AmDaemon</var> returns <code>True</code> if issued on a <var>Daemon</var>-associated thread; otherwise it returns <code>False</code>.</td></tr><br />
<br />
<tr><th><var class="nobr">%(Daemon)</var></th><br />
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>AmDaemon</var> can also be invoked via a <var>Daemon</var> object variable, which may be <var>Null</var>.</td></tr><br />
</table><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Since a daemon thread can run web requests, socket server requests, and <var>$CommndL</var> requests, <var>AmDaemon</var> distinguishes a daemon thread that is working for a <var>Daemon</var> object<br />
from, say, a daemon thread running a web request. This distinction is particularly important for certain methods, such as <var>ReturnToMaster</var> or <var>ReturnObject</var>, that can only be issued on a thread associated with a <var>Daemon</var> object. </li><br />
<br />
<li>If a daemon thread was spawned by <var>[[RunIndependently (Daemon subroutine)|RunIndependently]]</var>, <var>AmDaemon</var> returns <code>False</code> since the daemon thread has no returnable objects. </li> <br />
</ul><br />
<br />
==See also==<br />
{{Template:Daemon:AmDaemon footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=RunIndependently_(Daemon_subroutine)&diff=116751RunIndependently (Daemon subroutine)2018-08-27T16:33:04Z<p>JAL: /* Exceptions */ remove Sirius Mods version reference</p>
<hr />
<div>{{Template:Daemon:RunIndependently subtitle}}<br />
<var>RunIndependently</var> runs on the daemon thread the command or set of commands specified by its first argument. Unlike <var>[[Run_(Daemon_function)|Run]]</var>, this method returns immediately, and the thread issuing <var>RunIndependently</var> can run in parallel with the <var>daemon</var> thread. Unlike <var>[[RunAsynchronously_(Daemon_subroutine)|RunAsynchronously]]</var>, this method makes the <var>daemon</var> thread completely independent of the parent thread, so the output from the commands can never be retrieved.<br />
<br />
==Syntax==<br />
{{Template:Daemon:RunIndependently syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>daemon</th><br />
<td>A previously defined <var>Daemon</var> object. </td></tr><br />
<tr><th>commands</th><br />
<td>A string or <var>[[Stringlist class|Stringlist]]</var> that is the command or the set of commands executed by the <var>daemon</var>.</td></tr><br />
<tr><th><var>Input</var></th><br />
<td>An object passed to the <var class="term">daemon</var> object. This optional, [[Notation conventions for methods#Named parameters|name allowed]], argument is passed by deep copy and not by reference, so <var class="term">object</var> must be deep copyable, as described in [[Copying objects|"Copying objects"]].</td></tr><br />
</table><br />
<br />
==Exceptions==<br />
<var>RunIndependently</var> can throw the following exception:<dl><br />
<br />
<dt><var>[[DaemonLost_class|DaemonLost]]</var> <br />
<dd>If the <var>daemon</var> object is lost (probably restarted), a <var>DaemonLost</var> exception is thrown. Since <var>RunIndependently</var> does not wait for the <var>daemon</var> thread to do anything, a <var>DaemonLost</var> exception indicates that the <var>daemon</var> thread was lost <b><i>before</i></b> <var>RunIndependently</var> was invoked. <br />
</dl><br />
<br />
==Usage notes==<br />
<ul><br />
<li>Issuing <var>RunIndependently</var> against a [[Daemon class#Transactional daemons|transactional daemon]] results in request cancellation. <br />
<li>If the <var class="term">daemon</var> thread and its daemons hold record locks that conflict with the parent thread's family (excluding the <var class="term">daemon</var> thread itself and its daemons), <var>RunIndependently</var> results in request cancellation.<br />
<li><var>RunIndependently</var> is the rough <var>Daemon</var> class equivalent of the <var>[[$CommBg|$CommBg]]</var> function. <br />
<li>After a <var>RunIndependently</var> method, the <var class="term">daemon</var> object is set to null. This is because the <var class="term">daemon</var> thread runs completely independently of the parent thread once a <var>RunIndependently</var> method is invoked, so there is nothing useful the parent thread can do with such a daemon, anyway. <br />
<li>The passing of objects and commands to daemons is identical whether the method is <var>[[Run_(Daemon_function)|Run]]</var> or <var>RunIndependently</var> &mdash; see [[Daemon class#Working with Daemon objects|"Working with Daemon objects"]] for more information about passing commands and objects to a daemon. <br />
<li>Even if the parent thread of an independently running daemon logs off, the daemon thread can continue to run. <br />
<li>No <var>Daemon</var> class mechanism is provided for a parent thread to retrieve the output from an independently running <var>Daemon</var>.<br />
<li>As described in [[Daemon class#Working with Daemon objects|"Working with Daemon objects"]], the <var>RunIndependently</var> <var class="term">commands</var> argument can pass multiple commands to the <var class="term">daemon</var> method object. <br />
<li>For more information about independent daemons, see [[Daemon class#Asynchronous and Independent daemons|"Asynchronous and Independent daemons"]].<br />
</ul><br />
<br />
==Examples==<br />
<p class="code">%daem:runIndependently(%list2, %x)<br />
</p><br />
<br />
==See also==<br />
{{Template:Daemon:RunIndependently footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=SERV4G_parameter&diff=116745SERV4G parameter2018-08-22T14:58:15Z<p>JAL: restore "under construction" note</p>
<hr />
<div>{{Template:SERV4G parameter subtitle}}<br />
<br />
This page is [[under construction]].<br />
<br />
==Summary==<br />
<dl><br />
<dt>Default value<br />
<dd>0<br />
<dt>Parameter type<br />
<dd>System<br />
<dt>Where set<br />
<dd>User 0 parameter line<br />
<dt>Related products<br />
<dd>All<br />
<dt>Introduced<br />
<dd><var class="product">Model 204</var> version 7.8<br />
</dl><br />
<br />
==Description==<br />
<p><br />
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is X'FFFFF000', each ATB server will begin at <code><i>XX</i>_FFFFF000</code>. If <var>SERV4G</var> is X'FFFF0000', each ATB server will begin at <code><i>XX</i>_FFFF0000</code>. <code><i>XX</i></code> is determined by the storage available on the system. </p><br />
<p><br />
The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter. </p><br />
<br />
==Example==<br />
<p><br />
If you want [[VTBL]] to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200</code> (6400 bytes, X'1900'). This will force each server's VTBL to begin at <code><i>XX</i>_FFFFF000</code> and end at <code><i>XX</i>+1_00000900</code>.<br />
</p><br />
<br />
[[Category:Parameters]]<br />
[[Category:System parameters]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=SERV4G_parameter&diff=116744SERV4G parameter2018-08-21T23:12:54Z<p>JAL: misc formatting</p>
<hr />
<div>{{Template:SERV4G parameter subtitle}}<br />
<br />
==Summary==<br />
<dl><br />
<dt>Default value<br />
<dd>0<br />
<dt>Parameter type<br />
<dd>System<br />
<dt>Where set<br />
<dd>User 0 parameter line<br />
<dt>Related products<br />
<dd>All<br />
<dt>Introduced<br />
<dd><var class="product">Model 204</var> version 7.8<br />
</dl><br />
<br />
==Description==<br />
<p><br />
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is X'FFFFF000', each ATB server will begin at <code><i>XX</i>_FFFFF000</code>. If <var>SERV4G</var> is X'FFFF0000', each ATB server will begin at <code><i>XX</i>_FFFF0000</code>. <code><i>XX</i></code> is determined by the storage available on the system. </p><br />
<p><br />
The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter. </p><br />
<br />
==Example==<br />
<p><br />
If you want [[VTBL]] to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200</code> (6400 bytes, X'1900'). This will force each server's VTBL to begin at <code><i>XX</i>_FFFFF000</code> and end at <code><i>XX</i>+1_00000900</code>.<br />
</p><br />
<br />
[[Category:Parameters]]<br />
[[Category:System parameters]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=Application_Subsystem_development&diff=116743Application Subsystem development2018-08-21T23:11:41Z<p>JAL: /* Advantages of subsystems */ add nowrap</p>
<hr />
<div>==Overview==<br />
<p><br />
Although only a system manager can define a subsystem, the determination of a subsystem's options and components typically also involves the file manager and application developer. This page focuses on subsystem facility topics most relevant to the application developer:</p><br />
<p><br />
The Subsystem Management facility of Dictionary lets you define a collection of procedures to <var class="product">Model&nbsp;204</var> as a subsystem and to assign certain characteristics to that subsystem. </p><br />
<br />
===Advantages of subsystems===<br />
<p><br />
The following table summarizes the advantages of subsystems over other [[SOUL]] procedure applications: </p><br />
<table><br />
<tr class="head"><br />
<th>Advantage </th><br />
<th>Subsystems...</th><br />
</tr><br />
<br />
<tr><br />
<td nowrap>Minimal end-user intervention </td><br />
<td>Require minimal knowledge of <var class="product">Model&nbsp;204</var>. The end user need not know what files and procedures exist for the application. The subsystem is invoked simply by entering the subsystem name as a <var class="product">Model&nbsp;204</var> command.</td><br />
</tr><br />
<br />
<tr><br />
<td>Driver facility </td><br />
<td>Eliminate the need for user-written drivers containing conditional INCLUDEs based on a global variable. This driver facility leads to smaller, more modular procedures that are easier to maintain and enhance.</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap>Performance improvements </td><br />
<td>Improve performance by saving and reloading compiled SOUL requests, called precompiled procedures. Depending upon how often precompiled procedures are included, 20-90% of the operating costs of a <var class="product">Model&nbsp;204</var> application can be saved.</td><br />
</tr><br />
<br />
<tr><br />
<td>Error handling facilities </td><br />
<td>Trap and handle <var class="product">Model&nbsp;204</var> errors in a single, centralized routine. Each subsystem can have one error procedure that is invoked each time a <var class="product">Model&nbsp;204</var> error occurs during that subsystem's processing. <var class="product">Model&nbsp;204</var> provides facilities for determining the type of error that caused the error procedure to be invoked. </td><br />
</tr><br />
<br />
<tr><br />
<td>Security facilities </td><br />
<td>Allow or restrict access to the subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Parallel Query Option/204 compatibility </td><br />
<td>Can be defined to allow referral to remote files and scattered groups.</td><br />
</tr><br />
</table><br />
<br />
===Subsystem definition===<br />
<p><br />
The characteristics and components of a subsystem are defined to <var class="product">Model&nbsp;204</var> by the system manager during a process called subsystem definition. The defined options and components are stored in the system file CCASYS. Once a subsystem has been defined, all Dictionary users can display the options and components through Dictionary. For more information about:</p><br />
<ul><br />
<li>Displaying a subsystem definition, see [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|Overview of the Subsystem Management facility]]. </li><br />
<br />
<li>Defining subsystems that refer to remote files and scattered groups, see [[PQO: Scattered APSY subsystems#Client and service subsystems|PQO client and service subsystems]]. <br />
</li><br />
</ul><br />
<br />
==Subsystem design components==<br />
<p><br />
During subsystem definition, the components listed below can be defined. These components impact various aspects of subsystem design. The following table summarizes the required component designations. </p><br />
<table><br />
<tr class="head"><br />
<th>Component </th><br />
<th>Subsystem design requires designation of...</th><br />
</tr><br />
<br />
<tr><br />
<td nowrap>Command line global variable </td><br />
<td>(Optional) parameter global variable. The parameter global variable allows any parameters specified by a user during a subsystem login to be stored in this variable and retained when control is transferred to another subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Communication global variable and exit value </td><br />
<td>Communication global variable and exit value. The communication global variable is used to transfer control from one procedure to another. The exit value is used to leave the subsystem. Optionally, a reserved global variable is available for transferring control between subsystems. </td><br />
</tr><br />
<br />
<tr><br />
<td>Error global variable </td><br />
<td>Error global variable. If an error occurs while the subsystem is executing, a three-character error code is stored in this variable. This code can then be used by an error procedure to determine the action to be taken by the subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Prefix designations </td><br />
<td>Two prefixes for procedure names. These prefixes allow <var class="product">Model&nbsp;204</var> to determine whether a procedure can be saved in its compiled form for later evaluation. </td><br />
</tr><br />
<br />
<tr><br />
<td>Processing components</td><br />
<td>Specific procedures for types of special processing. These procedures allow <var class="product">Model&nbsp;204</var> to determine the flow of control within a subsystem. </td><br />
</tr><br />
</table><br />
<br />
==Command line global variable==<br />
<p><br />
A command line global variable allows you to store any parameters specified by an end user during a subsystem login and retain this information when control is transferred to another subsystem. The designation of a command line global variable is optional. </p><br />
<br />
===Using the command line global variable===<br />
<p><br />
The command line global variable is used in the following manner:</p><br />
<ul><br />
<li>A user logs into a subsystem by entering the subsystem name followed by the parameter information. The total length of the parameter information entered by the user can consist of as many as 255 characters. (The portion of the command line reserved for parameter information is discarded if no parameter information is defined.)</li><br />
<br />
<li>The portion of the input following the subsystem name is placed into a command line global variable, which then is available to the application program. For example:<br />
<p class="syntax">PAYROLL <span class="term">parameter1 parameter2</span><br />
</p><br />
<p><br />
is the command that logs the current user into the subsystem named PAYROLL. The string <i>parameter1 parameter2</i> is the subsystem command line and is made available to the application via a global variable. If CMDL is the name assigned to the command line global variable, the following statements:</p><br />
<p class="code">BEGIN<br />
%CMD.LINE = $GETG('CMDL')<br />
%FIRST.PARM =<br />
$Substr(%CMD.LINE,1,$INDEX(%CMD.LINE,' ')-1)<br />
</p><br />
<p><br />
would assign the contents of the command line used to enter the subsystem to %CMD.LINE and the first parameter of the line to %FIRST.PARM. </p><br />
</li><br />
</ul><br />
<br />
===Transferring control to another subsystem===<br />
<p><br />
The contents of command line global variables are not deleted when control is transferred from one subsystem to another. A request can set the contents of the command line global variable of the destination subsystem before transferring control to that subsystem. The effect is the same as if the parameters were entered on the user's terminal. </p><br />
<br />
===Impact of the UTABLE command===<br />
<p><br />
The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. </p><br />
<br />
==Communication global variable==<br />
<br />
===Transferring control===<br />
<p><br />
A communication global variable lets you transfer control at two levels: </p><br />
<table><br />
<tr class="head"><br />
<th>From... </th><br />
<th>Control is transferred by a...</th><br />
</tr><br />
<br />
<tr><br />
<td>One procedure to another </td><br />
<td>User-designated global variable.</td><br />
</tr><br />
<br />
<tr><br />
<td>One subsystem to another </td><br />
<td>Reserved global variable named XFER. </td><br />
</tr><br />
</table><br />
<br />
===Transferring control between procedures===<br />
<p><br />
Subsystem procedures pass control from one to another through the use of the communication global variable. The communication global variable name for a subsystem is specified in the subsystem definition. Each subsystem procedure must set the value of the communication global variable to the name of the next procedure to be executed.</p><br />
<br />
====Example====<br />
<p><br />
For example, the subsystem AUTOS has procedures PRE-MAIN.MENU and PRE-RPT.PGM and the communication global variable NEXT.<br />
PRE-MAIN.MENU is currently executing and wants to pass control to<br />
PRE-RPT.PGM. Before PRE-MAIN.MENU finishes, the function $SETG is used to store procedure name PRE-RPT.PGM in NEXT:</p><br />
<p class="code">IF $SETG('NEXT','PRE-RPT.PGM') THEN ...<br />
</p><br />
<p><br />
After PRE-MAIN.MENU ends, <var class="product">Model&nbsp;204</var> examines NEXT and begins executing PRE-RPT.PGM.</p><br />
<br />
====Subsystem exit value====<br />
<p><br />
A subsystem is exited by setting the value of the communication global variable to the subsystem exit value. The exit value for the communication global variable is also specified in the subsystem definition. </p><br />
<p><br />
For the AUTOS subsystem used in the preceding example, the exit value of the communication global variable is defined as EXIT. To disconnect the user from the AUTOS subsystem after procedure PRE-RPT.PGM is finished executing, PRE-RPT.PGM assigns the exit value, EXIT, to the communication global variable, NEXT.</p><br />
<p class="code">IF $SETG('NEXT','EXIT') THEN<br />
.<br />
.<br />
.<br />
</p><br />
<br />
===Transferring control between subsystems===<br />
<p><br />
One subsystem can invoke another subsystem by transferring control from itself to another subsystem. To accomplish this, you must perform these steps:</p><br />
<ol><br />
<li>Set the communication global variable to the value XFER.</li><br />
<li>Set the global variable XFER to the name of the subsystem to which control is being passed. </li><br />
</ol><br />
<p><br />
When the current procedure finishes executing, <var class="product">Model&nbsp;204</var> disconnects the user from the old subsystem, transfers control to the new subsystem, and invokes the login procedure for the new subsystem. </p><br />
<br />
====Design considerations====<br />
<p><br />
You should consider the following factors when coding logic for transferring control between two subsystems:</p><br />
<ul><br />
<li>The transfer always invokes the login procedure of the subsystem receiving control. For more information on the login procedure, refer to the discussion [[#Subsystem processing flow|Subsystem processing flow]].</li><br />
<br />
<li>The destination subsystem must be active. The $SUBSYS function should be used to determine if the subsystem to which control is being transferred is active; refer to the discussion on [[#Subsystem procedure control functions|Subsystem procedure control functions]]. If the destination subsystem does not use the automatic start option, (see [[#Operating options|Operating options]]), the subsystem must be started before control is passed. </li><br />
<br />
<li>The destination subsystem should not reset LGTBL if any parameters are passed in global variables. </li><br />
<br />
<li>To return to the original subsystem, a global variable must be set to the name of the original subsystem. The communication global variable and the XFER global variable can then be used with the global variable that stores the subsystem name to return control to the original subsystem.</li><br />
<br />
<li>The destination subsystem can return control to the procedure that the user was in when the user transferred. To do this, the subsystem must save the name of the procedure in a global variable. In addition, the login procedure must contain logic to return control to the procedure that the user was in.</li><br />
<br />
<li>If the transferring subsystem is in test mode (see [[#Security options|Security options]]), the transferring subsystem stops after it passes control. The destination subsystem is not placed in test mode. <br />
</li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
The following request in procedure PRE-SUB.MENU provides an example of subsystem transfer code. CREDIT and AUTOS are two defined subsystems with the automatic start option. (See [[#Automatic start|Automatic start]].) Subsystem CREDIT transfers control to AUTOS by setting NEXT (the communication global variable) to XFER and the global variable XFER to AUTOS. After the PRE-SUB.MENU procedure ends, the user is connected to AUTOS.</p><br />
<p class="code">BEGIN<br />
.<br />
.<br />
.<br />
<b></b>*SELECTION = 4 INDICATES CHOICE OF AUTOS SUBSYSTEM<br />
<b></b>*<br />
SEL.AUTOS: IF %CREDITMENU:SELECTION = 4 AND -<br />
$SUBSYS('AUTOS') =1 THEN<br />
IF $SETG('XFER','AUTOS') OR -<br />
$SETG('NEXT','XFER') OR -<br />
$SETG('SUBFROM','CREDIT') OR -<br />
$SETG('PROCFROM','PRE-SUB.MENU') THEN<br />
PRINT 'GLOBAL TABLE FULL'<br />
END IF<br />
JUMP TO GET.NEXT<br />
.<br />
.<br />
.<br />
</p><br />
<br />
===Coding considerations===<br />
<ul><br />
<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li><br />
<br />
<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li><br />
<br />
<li>To exit the subsystem, the communication global variable must be set to the exit value. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used. <br />
</li><br />
</ul><br />
<br />
==Error global variable==<br />
<p><br />
The name of the error global variable must be specified in the subsystem definition. Whenever an error is detected that is not trapped by an ON unit, <var class="product">Model&nbsp;204</var> automatically sets the subsystem's error global variable to a value which indicates the type of error that occurred. </p><br />
<br />
===Error code values===<br />
<p><br />
The "Error global variable values and reasons" table lists the error global variable values and their corresponding causes. Correct the cause of the error, and/or change your error procedure as discussed in [[#Error procedures|Error procedures]]. </p><br />
<table><br />
<caption>Error global variable values and reasons</caption><br />
<tr class="head"><br />
<th>Error code</th><br />
<th>Reason</th><br />
</tr><br />
<br />
<tr><br />
<td>ATN </td><br />
<td>User pressed attention</td><br />
</tr><br />
<br />
<tr><br />
<td>BUG </td><br />
<td>Evaluation errors</td><br />
</tr><br />
<br />
<tr><br />
<td>CAN</td><br />
<td>Request evaluation canceled due to invalid terminal I/O in error procedure after BUMP or inactive thread time out.</td><br />
</tr><br />
<br />
<tr><br />
<td>CNT </td><br />
<td>Counting errors</td><br />
</tr><br />
<br />
<tr><br />
<td>FIL - BROKEN </td><br />
<td>Referenced file is not initialized, full, or physically inconsistent. Check the audit trail to determine the condition of the file. </td><br />
</tr><br />
<br />
<tr><br />
<td>FIL - NOT OPEN </td><br />
<td>Referenced file not open</td><br />
</tr><br />
<br />
<tr><br />
<td>GRP - FTBL </td><br />
<td>FTBL too small</td><br />
</tr><br />
<br />
<tr><br />
<td>GRP - NOT OPEN </td><br />
<td>Group not open</td><br />
</tr><br />
<br />
<tr><br />
<td>GRP - TEMP FIELD </td><br />
<td>TEMP group field has wrong type (see [[#Restrictions for temporary and ad hoc groups in precompiled procedures|Restrictions for temporary and ad hoc groups in precompiled procedures]])</td><br />
</tr><br />
<br />
<tr><br />
<td nowrap>GRP - TEMP MISMATCH </td><br />
<td>TEMP group has wrong type</td><br />
</tr><br />
<br />
<tr><br />
<td>INCLUDE MAX</td><br />
<td>Maximum iterations value has been exceeded.</td><br />
</tr><br />
<br />
<tr><br />
<td>HNG </td><br />
<td>Phone hung up, connection lost</td><br />
</tr><br />
<br />
<tr><br />
<td>HRD </td><br />
<td>Hard restart</td><br />
</tr><br />
<br />
<tr><br />
<td>REC </td><br />
<td>Record locking table filled up during the load of a<br />
precompiled request</td><br />
</tr><br />
<br />
<tr><br />
<td>RFR</td><br />
<td>After several tries, an APSY failed to invoke a procedure, because the procedure is in the process of being refreshed.</td><br />
</tr><br />
<br />
<tr><br />
<td>SFT </td><br />
<td>Soft restart</td><br />
</tr><br />
<br />
<tr><br />
<td>TBL - FSCB </td><br />
<td>FSCB too small</td><br />
</tr><br />
<br />
<tr><br />
<td>TBL - NTBL </td><br />
<td>NTBL too small</td><br />
</tr><br />
<br />
<tr><br />
<td>TBL - QTBL </td><br />
<td>QTBL too small</td><br />
</tr><br />
<br />
<tr><br />
<td>TBL - STBL </td><br />
<td>STBL too small</td><br />
</tr><br />
<br />
<tr><br />
<td>TBL - VTBL </td><br />
<td>VTBL too small</td><br />
</tr><br />
</table><br />
<br />
===Error procedures===<br />
<p><br />
An error procedure must test for different error conditions. The resulting value stored in the error global variable helps the application programmer determine the type of error that occurred.</p><br />
<ul><br />
<li>For all error codes except ATN, the error procedure should avoid re-executing the procedure that caused the error; otherwise, the error recurs. </li><br />
<br />
<li>In most cases, the error procedure should display an informational message and set the global communication variable to the exit value. </li><br />
<br />
<li>If a HNG error code is indicated, all terminal I/O (such as PRINT, READ) is ignored. </li><br />
<br />
<li>If a HNG, HRD, or SFT error code is indicated, no terminal I/O (such as PRINT or READ) should be attempted. Instead, send a message to the audit trail in an AUDIT statement that indicates the error code encountered. <br />
</li><br />
</ul><br />
<br />
====Considerations for the communications global variable====<br />
<p><br />
The communications global variable is ignored and disconnect processing completed when one of the following conditions occurs:</p><br />
<ul><br />
<li>Error is a soft restart, a hard restart, or a phone hang-up condition. <br />
<p><br />
If you attempt to set the communications global variable to the name of another procedure, the procedure is not executed.</p><br />
</li><br />
<br />
<li>No error procedure is specified in the subsystem definition. <br />
</li><br />
</ul><br />
<p><br />
An example illustrating how a subsystem error procedure can test for different error conditions is provided in [[#Error procedure|Error procedure]]. </p><br />
<br />
==Precompiled and non-precompiled procedures==<br />
<p><br />
You can use two types of procedures in a subsystem: </p><br />
<ul> <br />
<li><b>Precompiled procedure</b><br />
<p> <br />
The first time a precompilable procedure is invoked after a subsystem starts, it is compiled and stored for re-use. Because the compiler phase is bypassed each subsequent time the procedure is invoked (except as noted below), precompilation saves both CPU and elapsed time. Exceptions include the following:</p><br />
<ul><br />
<li>The procedure is recompiled the first time it is invoked for each SCLASS. The new compilation is evaluated, then discarded. It does not replace the original stored compilation. </li><br />
<li>Further recompilations might be required due to temporary group differences. See [[#Recompiling precompiled procedures|Recompiling precompiled procedures]] for more on this. </li><br />
</ul></li><br />
<br />
<li><b>Non-precompiled procedure</b><br />
<p> <br />
A non-precompiled procedure is compiled each time it is invoked.</p></li><br />
</ul><br />
<p><br />
All procedures, whether precompiled or not, are invoked using the communication global variable.</p><br />
<br />
===Defining prefixes===<br />
<p><br />
During subsystem definition, two prefixes must be defined. The first prefix identifies precompiled procedures; the second identifies non-precompiled procedures. All procedures that are included for the subsystem through the use of the communication global variable (such as the login and main processing procedures) must have names that begin with one of these prefixes.</p><br />
<br />
===Contents of subsystem procedures===<br />
<p><br />
Subsystem procedures can contain <var class="product">Model&nbsp;204</var> commands, a request, multiple requests, continued requests, sections of User Language code (for example, subroutines), or any combination thereof. However, the form of the procedure affects whether the procedure can be precompiled and should be taken into account when the subsystem is designed. Restrictions for precompiled procedures are discussed in detail below.</p><br />
<br />
===Shared versions of precompiled procedures===<br />
<p><br />
Server I/O can be reduced by allowing users executing shared precompiled procedures to use a shared version of QTBL.<br />
See [[Performance monitoring and tuning#Resident Request feature for precompiled procedures|Resident Request feature for precompiled procedures]]. </p><br />
<br />
===Restrictions for precompiled procedures===<br />
<p><br />
<var class="product">Model&nbsp;204</var> must ensure that all of the code compiled and saved for a request with the precompiled prefix is consistent for all loading users. To achieve consistency, <var class="product">Model&nbsp;204</var> restricts the way in which certain features are used. </p><br />
<p><br />
Note the following restrictions for precompiled procedures when designing subsystem procedures:</p><br />
<ul><br />
<li>Procedures must contain exactly one request. The last statement must be END or END MORE.</li><br />
<br />
<li>Requests cannot start with MORE.</li><br />
<br />
<li>Procedures that include multiple BEGIN/END blocks are not eligible for precompilation.</li><br />
<br />
<li>Requests must not refer to files or permanent groups that are not mentioned in the subsystem definition.</li><br />
<br />
<li>Precompiled procedures can contain the User Language INCLUDE statement. The included procedures must be from a subsystem file. Any code inserted as a result of an INCLUDE statement is subject to all the restrictions for precompiled procedures. </li><br />
<br />
<li>If a precompiled procedure issues the INCLUDE command to compile and run a User Language request, the INCLUDE command is saved, not the compilation of the request that was included.</li><br />
<br />
<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li><br />
<br />
<li>Dummy strings (??, ?$, ?&amp;) in precompiled procedures are resolved only during compilation for the first user.</li><br />
<br />
<li>Dummy string substitution does not take place when saving commands that contain dummy strings. Instead, when the saved commands are loaded and executed, the current value of the dummy string is used. For example, if you include the following command in a precompiled procedure, whatever is currently in the global COMMAND is executed. <br />
<p class="code">?%COMMAND<br />
</p></li><br />
<br />
<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li><br />
<br />
<li>Procedures in UNLOCKed members of a PROCFILE GROUP are not precompiled. <br />
</li><br />
</ul><br />
<br />
===Restrictions for temporary and ad hoc groups in precompiled procedures===<br />
<p><br />
Precompiled requests can refer to temporary or ad hoc groups as long as the files making up the group are specified in the subsystem definition. A temporary group of the same name must have the same composition characteristics for all loading users, as described below. If this condition is not met, <var class="product">Model&nbsp;204</var> sets the error global variable to GRP-TEMP MISMATCH (see [[#Error global variable|Error global variable]]).</p><br />
<ul><br />
<li>The temporary group for all loading users must be the same type. <var class="product">Model&nbsp;204</var> assigns a type, based on the following file conditions:<br />
<ul><br />
<li>Some files have record security.</li><br />
<li>All files are sorted or all are hashed.</li><br />
<li>The sort or hash key has the same name in all files. </li><br />
</ul></li><br />
<br />
<li>Fields of the same name in the temporary group must be of the same type. Each field referenced in a temporary group each time a precompiled procedure is invoked must be found in a file. If this condition is not met, <var class="product">Model&nbsp;204</var> sets the error global variable to GRP-TEMP FIELD (see [[#Error global variable|Error global variable]]). <br />
<p><br />
Field definition attributes can change for fields in temporary groups between compile and loading time. The following changes are allowed:</p><br />
<ul><br />
<li>If the field is NON-CODED in any file at compile time, it can be CODED in all files at loading time.</li><br />
<li>If the field is BINARY or FLOAT in any file at compile time, it can be STRING in all files at loading time.</li><br />
<li>If the field is non-NUMERIC RANGE in any file at compile time, the field can be NUMERIC RANGE in all of the files at loading time.</li><br />
</ul></li><br />
</ul><br />
<br />
===Recompiling precompiled procedures===<br />
<p><br />
When designing applications which use precompiled procedures and temporary groups, be aware that temporary groups can cause <var class="product">Model&nbsp;204</var> to recompile precompiled procedures under certain conditions. </p><br />
<p><br />
Precompiled procedures are recompiled when the request references a temporary group and the:</p><br />
<ul><br />
<li>Compiling user's temporary group consists of files which are smaller than one or more of the files in the loading user's temporary group of the same name.</li><br />
<br />
<li>Compiling user's temporary group has fewer files than the loading user's temporary group of the same name. </li><br />
<br />
<li>Update and retrieve privileges do not match those of the compiling user's temporary group (of the same name). <br />
</li><br />
</ul><br />
<p><br />
If one user's temporary group contains one large file, and another user's temporary group contains a number of smaller files, it is possible that a precompiled procedure is recompiled every time it is invoked. To prevent constant recompiling when files are of different sizes, compile temporary groups originally with the largest files and the greatest number files you expect to be included in the temporary group.</p><br />
<p><br />
If, despite precautions, <var class="product">Model&nbsp;204</var> must discard and recompile a precompiled procedure, the loading user must have exclusive access to that procedure: no other user can be executing the procedure within the same subsystem. If another user is executing the procedure, the loading user recompiles a private copy of the procedure. <var class="product">Model&nbsp;204</var> discards the private copy when execution has completed. </p><br />
<br />
===Procedure compilation and Parallel Query Option/204===<br />
<p><br />
When a non-precompiled procedure that references remote files is invoked, one or more remote nodes participate in the compilation and evaluation. When a precompiled procedure is invoked, <var class="product">Model&nbsp;204</var> loads the procedure on each of the nodes that participated in the original compilation.</p><br />
<p><br />
When a subsystem member becomes unavailable during evaluation, the appropriate ON unit is activated. </p><br />
<p><br />
Errors which occur while loading a remote procedure produce error messages which have the prefix RMT in the global error variable.</p><br />
<br />
====Saving compilations====<br />
<p><br />
As part of the compilation process, a list of remote nodes referenced in the request is generated with the compiled code. When compilation is complete, the compilation is saved along with the list of nodes. Each remote node referenced in the request is sent a signal to save the compilation. </p><br />
<p><br />
If for any reason a compilation cannot be saved by a server node, the entire save operation fails.</p><br />
<br />
====Loading saved compilations====<br />
<p><br />
At the client node, the saved remote node reference list is checked to see which nodes are loading the request. When the request is loaded on the client, a signal is transmitted to each referenced server node to load the compilation. </p><br />
<br />
====New and missing nodes====<br />
<p><br />
A temporary group can be changed so that a node is <b>new</b> (not previously referenced) or <b>missing</b> (referenced but no longer available). [[#New and missing nodes|Temporary groups with new and missing nodes]] shows how new and missing nodes affect recompilations and saves. </p><br />
<table><br />
<caption>Temporary groups with new and missing nodes</caption><br />
<tr class="head"><br />
<th>&nbsp;</th><br />
<th>If there are<br />
missing nodes...</th><br />
<th>If there are no<br />
missing nodes....</th><br />
</tr><br />
<br />
<tr><br />
<td>And there are new nodes...</td><br />
<td>Recompile the procedure, do not save</td><br />
<td>Recompile and save again</td><br />
</tr><br />
<br />
<tr><br />
<td>And there are no new nodes...</td><br />
<td>Just load and evaluate</td><br />
<td>Just load and evaluate</td><br />
</tr><br />
</table> <br />
<br />
====Recompiling saved requests====<br />
<p><br />
Saved requests are always recompiled if a new node is introduced into a temporary group. Recompilation can cause a noticeable delay in response time.</p><br />
<p><br />
In addition, the following changes in the composition of a subgroup also force recompilation of a request. A subgroup is the group of files at a server node referenced as a part of a group.</p><br />
<p><br />
<var class="product">Model&nbsp;204</var> recompiles saved requests when:</p><br />
<ul><br />
<li>The number of files in the subgroup has increased (for example, if a user's request includes a file that was unavailable to the previous user)</li><br />
<br />
<li>The maximum number of segments in a subgroup has increased <br />
</li><br />
</ul><br />
<br />
==Subsystem procedures==<br />
<br />
===Types of subsystem procedures===<br />
<p><br />
Subsystem development involves writing the collection of procedures that make up a subsystem. Subsystem procedures can be categorized as one of four types: </p><br />
<table><br />
<tr class="head"><br />
<th>Procedure category </th><br />
<th>Performs...</th><br />
</tr><br />
<br />
<tr><br />
<td><var>Initialization</var> </td><br />
<td>Specified operations each time the subsystem is initialized.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Login</var> </td><br />
<td>As the entry point for each user of the subsystem.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Main processing</var> </td><br />
<td>Specific tasks of the subsystem.</td><br />
</tr><br />
<br />
<tr><br />
<td><var>Error</var> </td><br />
<td>Error handling. </td><br />
</tr><br />
</table><br />
<br />
===Guidelines and restrictions===<br />
<ul><br />
<li>Procedures should be small and modular.</li><br />
<br />
<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li><br />
<br />
<li>Non-subsystem files can be opened and referenced only by non precompiled procedures.</li><br />
<br />
<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li><br />
<br />
<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li><br />
<br />
<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li><br />
<br />
<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed. The default action for each type of message is listed in [[M204.1076]]. <br />
<p><br />
If you do not wish the default action to be executed, statements to handle a situation that would invoke the message should be added to the procedure. </p><br />
</li><br />
</ul><br />
<br />
===Initialization procedure===<br />
<p><br />
The initialization procedure stores instructions for tasks you need to perform each time the subsystem is initialized. An example of such a task is the initialization of a particular work file. </p><br />
<p><br />
The initialization procedure is optional. If a subsystem uses an initialization procedure, the procedure name must be specified in the subsystem definition.</p><br />
<br />
===Login procedure===<br />
<p><br />
The login procedure performs the start up for each user of an application. Every time a user invokes the subsystem, <var class="product">Model&nbsp;204</var> automatically includes the subsystem login procedure. </p><br />
<p><br />
The login procedure name must be specified in the subsystem definition. </p><br />
<p><br />
Typically, the login procedure is used to store current server table sizes in the global variable table for later reference, issue UTABLE commands to set compiler table sizes for the subsystem, and set the communication global variable to the name of the procedure that displays an initial menu. </p><br />
<b>Example</b><br />
<p><br />
Here is a sample login procedure:</p><br />
<p class="code">CLEARG<br />
BEGIN<br />
IF $SETG('NTBL',$VIEW('LNTBL')) OR -<br />
$SETG('VTBL',$VIEW('LVTBL')) OR -<br />
$SETG('QTBL',$VIEW('LQTBL')) OR -<br />
$SETG('STBL',$VIEW('LSTBL')) OR -<br />
$SETG('FSCB',$VIEW('LFSCB')) OR -<br />
$SETG('LECHO',$VIEW('LECHO')) OR -<br />
$SETG('NEXT','PRE-MAIN.MENU') THEN<br />
PRINT 'GTBL FULL'<br />
END IF<br />
END<br />
UTABLE LNTBL=450,LQTBL=2300,LVTBL=600,LSTBL=3300<br />
UTABLE LFSCB=5000<br />
RESET LECHO 0<br />
</p><br />
<br />
===Main processing procedures===<br />
<p><br />
Main processing procedures perform the specific tasks of the subsystem. There can be as few or as many main processing procedures as necessary for the subsystem to perform its tasks. Main processing procedures are not specified in the subsystem definition. However, each procedure must follow the procedure naming conventions and subsystem coding rules discussed on this page. </p><br />
<br />
====Example====<br />
<p><br />
Here is a sample procedure:</p><br />
<p class="code">BEGIN<br />
MENU MAINMENU<br />
TITLE 'AUTO INSURANCE SYSTEM (MAIN MENU)' AT 10 BRIGHT<br />
MAX PFKEY 12<br />
SKIP 5 LINES<br />
PROMPT 'MAINTENANCE' AT 10 BRIGHT<br />
SKIP 2 LINES<br />
PROMPT 'REPORTING' AT 10 BRIGHT<br />
SKIP 2 LINES<br />
PROMPT 'EXIT' AT 10 BRIGHT<br />
END MENU<br />
%NEXT = 'X'<br />
REPEAT WHILE %NEXT = 'X'<br />
READ MAINMENU<br />
IF %MAINMENU:SELECTION = '1' THEN<br />
%NEXT = 'PRE-MAINT.PGM'<br />
ELSEIF %MAINMENU:SELECTION = '2' THEN<br />
%NEXT = 'PRE-RPT.PGM'<br />
ELSE %NEXT = 'NON-FINISH'<br />
END IF<br />
END REPEAT<br />
CHK.GTAB: IF $SETG('NEXT',%NEXT) THEN<br />
AUDIT 'GLOBAL TABLE FULL - "NEXT"'<br />
END IF<br />
END<br />
</p><br />
<br />
===Error procedure===<br />
<p><br />
An error procedure, which is optional, performs error handling. This procedure is invoked when a condition occurs that cannot be trapped by the executing procedure (for example, a compiler error or an attention with no ON ATTENTION unit coded). An error procedure tests for different error conditions and determines the next procedure to execute, based on the error code value stored in the error global variable. Terminal I/O in a subsystem error procedure following a BUMP or inactive thread timeout results in cancellation of the procedure. </p><br />
<br />
====Example====<br />
<p><br />
The following error procedure assumes that the error global variable name is ERRCLASS, the communication global variable name is NEXT, and the exit value of the communication global variable is EXIT.</p><br />
<p class="code">PROCEDURE SYS-ERROR<br />
BEGIN<br />
<b></b>*<br />
<b></b>* GET THE VALUE OF THE ERROR CLASS GLOBAL VARIABLE<br />
<b></b>*<br />
GET.VALUE: %ERRORCODE = $GETG('ERRCLASS')<br />
<b></b>*<br />
<b></b>* IF THE USER HIT ATTENTION, INCLUDE THE MAIN MENU SCREEN<br />
<b></b>*<br />
IF.ERROR: IF %ERRORCODE = 'ATN' THEN<br />
%NEXT = 'SYS-MAIN-MENU'<br />
<b></b>*<br />
<b></b>* IF PHONE WAS HUNG UP, OR ANY KIND OF RESTART, THEN AUDIT<br />
<b></b>* MESSAGE AND EXIT. DO NOT ATTEMPT ANY TERMINAL I/O<br />
<b></b>* SINCE USER IS NO LONGER CONNECTED.<br />
<b></b>*<br />
ELSEIF %ERRORCODE = 'HNG' OR -<br />
%ERRORCODE = 'SFT' OR -<br />
%ERRORCODE = 'HRD' THEN<br />
AUDIT 'SUBSYSTEM ERROR CODE: ' -<br />
WITH %ERRORCODE<br />
%NEXT = 'EXIT'<br />
<b></b>*<br />
<b></b>* CHECK FOR BROKEN FILE<br />
<b></b>*<br />
ELSEIF %ERRORCODE = 'FIL - BROKEN' THEN<br />
PRINT ' SUBSYSTEM FILE IS BROKEN'<br />
PRINT ' CONTACT YOUR FILE MANAGER '<br />
%NEXT = 'EXIT'<br />
<b></b>*<br />
<b></b>* SOME UNACCOUNTABLE ERROR HAS OCCURRED, SET EXIT<br />
<b></b>* ROUTINE, AND EXIT WITHOUT DOING ANY TERMINAL I/O.<br />
<b></b>*<br />
ELSE<br />
AUDIT 'NOT ACCOUNTED FOR SUBSYSTEM ERROR CODE: ' -<br />
WITH %ERRORCODE<br />
%NEXT = 'EXIT'<br />
END IF IF.ERROR<br />
<b></b>*<br />
<b></b>* SET COMMUNICATIONS VARIABLE TO EXIT VALUE<br />
<b></b>*<br />
COMM.VAR: IF $SETG('NEXT',%NEXT) THEN<br />
AUDIT 'GTBL full in SYS-ERROR trying to set NEXT to ' WITH %NEXT<br />
PRINT 'GTBL FULL'<br />
END IF<br />
END.REQUEST: *<br />
END<br />
END PROCEDURE<br />
</p><br />
<br />
==Security options==<br />
<p><br />
During subsystem definition, various options are specified for a subsystem. Security options determine subsystem command and file and group privileges assigned to a user. </p><br />
<p><br />
You can also specify system operation options during subsystem definition. System operation options are discussed in the [[#Operating options|Operating options]] section.<br />
For a detailed discussion of subsystem definition options, refer to [[System requirements for Application Subsystems]]. </p><br />
<br />
===Status of subsystem===<br />
<p><br />
The status of the subsystem affects the type of subsystem security that is implemented. The subsystem can have one of three status settings: </p><br />
<table><br />
<tr class="head"><br />
<th>Status setting </th><br />
<th>Allows access to...</th><br />
</tr><br />
<br />
<tr><br />
<td>Public </td><br />
<td>All users. All users who enter a public subsystem are assigned to the single subsystem user class and have the same set of privileges. </td><br />
</tr><br />
<br />
<tr><br />
<td>Semipublic </td><br />
<td>All users but permits different privileges to be assigned for each user. In a semipublic subsystem, one subsystem user class can be defined as the default class for all users not specifically assigned to another subsystem user class. </td><br />
</tr><br />
<br />
<tr><br />
<td>Private </td><br />
<td>Only to specified users. Using a private subsystem prevents any unauthorized entry into the subsystem. All users who are allowed access must be assigned to one of the defined user classes. Unlike a semipublic subsystem, a private subsystem has no default user class. </td><br />
</tr><br />
</table><br />
<br />
===User class===<br />
<p><br />
The set of privileges assigned to a user is based on the user's subsystem user class or SCLASS. The SCLASS is used by <var class="product">Model&nbsp;204</var> to determine the privileges assigned for each file and group in the subsystem when files are opened for the user. File and group privileges must be specified in the subsystem definition because <var class="product">Model&nbsp;204</var> bypasses <var>OPENCTL</var> parameter settings and file passwords when opening subsystem files and groups for each user. Whenever the user invokes the subsystem, he/she is assigned the file and group privileges of that subsystem user class. </p><br />
<p><br />
The SCLASS also determines whether or not the user can issue any of the subsystem control commands listed below. If <var class="product">Model&nbsp;204</var> discovers that the user does not have the correct privileges to issue a command, an error message is displayed.</p><br />
<table><br />
<tr class="head"><br />
<th>Subsystem control commands </th><br />
<th>Directs Model&nbsp;204 to...</th><br />
</tr><br />
<br />
<tr><br />
<td><var>DEBUG SUBSYSTEM</var> </td><br />
<td>Establish a test environment for a multiuser version of the <var>TEST</var> command extension. The subsystem does not have to be stopped to issue the <var>DEBUG</var> command. <br />
<p><br />
When a user enters a subsystem in <var>TEST</var> or <var>DEBUG</var> mode, the user's MSGCTL parameter setting is not changed. All error and informational messages that are not suppressed by the user's <var>MSGCTL</var> setting are displayed on the user's terminal. </p><br />
</td><br />
</tr><br />
<br />
<tr><br />
<td><var>START SUBSYSTEM</var> </td><br />
<td>Activate the subsystem and make it available for use. If the subsystem is inactive when the <var>START</var> command is issued, <var class="product">Model&nbsp;204</var> opens all the subsystem files and includes the subsystem initialization procedure. </td><br />
</tr><br />
<br />
<tr><br />
<td><var>STOP SUBSYSTEM</var> </td><br />
<td>Stop the subsystem and make it unavailable for use. Once a subsystem is stopped and all users have exited, then all locking and storage resources held by the subsystem are released and all the subsystem files and groups are closed. </td><br />
</tr><br />
<br />
<tr><br />
<td><var>TEST</var> </td><br />
<td>Establish a single user test environment. The <var>TEST</var> command is extended to <var>TEST DEBUG SUBSYSTEM</var>. The subsystem must be stopped to enter <var>TEST</var> mode.</td></tr><br />
</table><br />
<br />
<p class="note"><b>Note:</b> Several aspects of <var>START SUBSYSTEM</var> and <var>STOP SUBSYSTEM</var> processing are unique to distributed applications. For a discussion, see [[PQO: Scattered APSY subsystems#Subsystem command processing|Subsystem command processing]].</p><br />
<br />
===Processing of security violations===<br />
<p><br />
The application subsystem traps security violations that occur while a user is running in a subsystem. File read and update security violations, procedure security violations, and field level security violations are interpreted as compilation or evaluation errors in the error global variable. The audit trail messages produced when the error occurred can be examined in order to identify a compilation or evaluation error as a security violation. </p><br />
<br />
===Compiling procedures with a different SCLASS===<br />
<p><br />
In the following situation, <var class="product">Model&nbsp;204</var> saves User 1's compilation:</p><br />
<ol><br />
<li>There are multiple SCLASSes for a subsystem.</li><br />
<li>User 1 saves a procedure under SCLASS 1.</li><br />
<li>User 2, under SCLASS 2, recompiles the procedure.</li><br />
<li>User 2's global variables contain different information from User 1's so User 2 tries to open different files or groups than User 1. </li><br />
</ol><br />
<p><br />
However, User 2's compilation is not saved: User 2 receives an error message:</p><br />
<p class="code">M204.0468: COMPILATION NOT SAVED - <i>reason</i><br />
</p><br />
<br />
==Operating options==<br />
<p><br />
Operating options affect certain aspects of the overall behavior of a subsystem. Operating options are distinct from security options, which are discussed in [[#Security options|Security options]].<br />
Subsystem options are also discussed in [[System requirements for Application Subsystems]]. </p><br />
<p><br />
The following table lists the operating options and what they determine.</p><br />
<table><br />
<tr class="head"><br />
<th>Operating option </th><br />
<th>Determines whether...</th><br />
</tr><br />
<br />
<tr><br />
<td>Automatic start </td><br />
<td>Subsystem automatically starts for the first user entering the subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Locking files and groups for subsystem use </td><br />
<td>Users from outside the subsystem can open and update subsystem files while the subsystem is active. </td><br />
</tr><br />
<br />
<tr><br />
<td>Automatic login </td><br />
<td>Users are automatically logged into <var class="product">Model&nbsp;204</var> upon entering a subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Automatic logout </td><br />
<td>Users are automatically logged out of <var class="product">Model&nbsp;204</var> upon exiting a subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Automatic COMMIT </td><br />
<td>Any outstanding updates are committed automatically whenever a subsystem procedure ends and transfers control using the communications global variable. </td><br />
</tr><br />
<br />
<tr><br />
<td>Message displays </td><br />
<td>Disconnect, informational, and error messages are displayed for subsystem users. </td><br />
</tr><br />
<br />
<tr><br />
<td>File usage </td><br />
<td>Subsystem can run when one or more files used by the subsystem are unavailable for use. </td><br />
</tr><br />
</table><br />
<br />
===Automatic start===<br />
<p><br />
If the automatic start option is selected, <var class="product">Model&nbsp;204</var> invokes subsystem initialization when the first user attempts to enter the subsystem. The subsystem can be used without a privileged user first issuing the START SUBSYSTEM command.</p><br />
<p><br />
If the automatic start option is not selected, subsystem initialization occurs only when the START SUBSYSTEM command is issued. The subsystem is then available for use. </p><br />
<br />
===Locking files and groups for subsystem use===<br />
<p><br />
If the locking files and groups option is selected, <var class="product">Model&nbsp;204</var> prevents users that are not running in the subsystem from opening any of the subsystem files or groups while the subsystem is active. </p><br />
<p><br />
If the locking files and groups option is not selected, users from outside the subsystem can retrieve, modify, or delete records in a subsystem file while the subsystem is active. </p><br />
<br />
===Automatic login===<br />
<p><br />
If the automatic login option is selected, <var class="product">Model&nbsp;204</var> logs on the user when the user enters a subsystem. The user is logged in using the subsystem name as the <var class="product">Model&nbsp;204</var> user ID. If the user already has logged into <var class="product">Model&nbsp;204</var> before entering the subsystem, <var class="product">Model&nbsp;204</var> first closes all the user's files and logs out the user. </p><br />
<p><br />
The LOGOUT operations that occur as a result of Automatic Login (both at subsystem Login and Disconnect) ignore the SYSOPT=8 (DISCONNECT on LOGOUT) option.</p><br />
<p><br />
If the login option is not selected, the user's <var class="product">Model&nbsp;204</var> user ID is used during subsystem processing. </p><br />
<br />
===Automatic logout===<br />
<p><br />
If the automatic logout option is selected, the user is logged out of <var class="product">Model&nbsp;204</var> upon exiting the subsystem. This option is particularly useful when combined with the automatic disconnect feature of <var class="product">Model&nbsp;204</var>. </p><br />
<p><br />
The START SUBSYSTEM command ignores the SYSOPT=8 option for the Automatic Logout subsystem.</p><br />
<p><br />
If the automatic logout option is not selected, <var class="product">Model&nbsp;204</var> logs the user out of the subsystem in one of three ways:</p><br />
<ul><br />
<li>If the user was previously logged into <var class="product">Model&nbsp;204</var>, <var class="product">Model&nbsp;204</var> restores the user's original user ID and returns the user to the <var class="product">Model&nbsp;204</var> command environment.</li><br />
<br />
<li>If the user was not previously logged into <var class="product">Model&nbsp;204</var>, the user is logged out of <var class="product">Model&nbsp;204</var>.</li><br />
<br />
<li>The SYSOPT=8 option causes the user to be disconnected from <var class="product">Model&nbsp;204</var>. <br />
</li><br />
</ul><br />
<br />
===Automatic COMMIT===<br />
<p><br />
If the automatic COMMIT option is selected, <var class="product">Model&nbsp;204</var> automatically issues a COMMIT statement for any outstanding updates whenever a subsystem procedure terminates and transfers control using the communication global variable. If the COMMIT option is not selected, the application must issue the COMMIT statement to commit any pending updates. </p><br />
<br />
===Message displays===<br />
<p><br />
<var class="product">Model&nbsp;204</var> provides these message display options for subsystem users: </p><br />
<ul><br />
<li>Disconnect message display</li><br />
<br />
<li><var class="product">Model&nbsp;204</var> informational message display</li><br />
<br />
<li><var class="product">Model&nbsp;204</var> error message display <br />
</li><br />
</ul><br />
<p><br />
When a message display option is selected, messages of that type are displayed on the user's terminal. If a message display option is not selected, all messages of that type are not displayed on the user's terminal. Note that if the display of any <var class="product">Model&nbsp;204</var> type message is suppressed, messages for the corresponding type are not displayed on the user's terminal, but are written to the audit trail file (CCAAUDIT).</p><br />
<p><br />
Typically, subsystem applications are written so that all messages displayed on the user's terminal are produced by the subsystem and <var class="product">Model&nbsp;204</var> messages are suppressed. </p><br />
<br />
===File usage===<br />
====Mandatory vs. optional members====<br />
<p><br />
Files and permanent groups contained within the subsystem definition can be designated as mandatory (the default) or optional members of the subsystem: </p><br />
<ul><br />
<li>Mandatory members<br />
<p> <br />
Mandatory files or groups are automatically opened by <var class="product">Model&nbsp;204</var> when a user logs into a subsystem and automatically closed when the user leaves the subsystem. Subsystem requests can assume that all mandatory files are open and that they are physically consistent. The user's file privileges are those defined in the subsystem definition for the current user's SCLASS. The opening of a mandatory member cannot be prevented by the subsystem administrator with the <var>STOP FILE</var> command when the subsystem is active. A mandatory member cannot be accessed by another copy of <var class="product">Model&nbsp;204</var> until the entire subsystem is stopped.</p> <br />
<p><br />
If a subsystem procedure issues an <var>OPEN</var> or <var>CLOSE</var> command for a mandatory member, the command is ignored by <var class="product">Model&nbsp;204</var> and the user's current privileges are not changed.</p></li><br />
<br />
<li>Optional members<br />
<p> <br />
Optional files or groups provide the ability for a file or group to be stopped by a subsystem administrator (using the <var>STOP FILE</var> command) without stopping the entire subsystem. If a member is defined as optional, it is not automatically opened during the subsystem login. It must be opened by the application by using an OPEN/OPENC statement or command. The file privileges assigned are those specified in the subsystem definition for the current user's SCLASS. The member is closed (for that user only) when the user leaves the subsystem if a <var>CLOSE</var> command has not been issued.</p><br />
<p><br />
When an optional member is not in use, it can be processed by another copy of <var class="product">Model&nbsp;204</var>. </p></li><br />
</ul><br />
<p><br />
Requests that reference mandatory or optional members can be precompiled. Files not contained in the subsystem definition can be opened and referenced within a subsystem application, but the requests that reference those files cannot be precompiled. </p><br />
<br />
====Automatic vs. manual members====<br />
<p><br />
Subsystem files and permanent group members can also be designated automatic or manual:</p><br />
<ul><br />
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li><br />
<br />
<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command. <br />
</li><br />
</ul><br />
<p><br />
Mandatory files cannot be designated manual. Optional files can be designated either automatic or manual.</p><br />
<br />
====Permanent vs. temporary groups in subsystem definitions====<br />
<p><br />
The GROUP parameter of the subsystem definition applies <strong>only</strong> to permanent groups. Temporary group names cannot be used. To include temporary group members in a subsystem definition, and thus to enable their use in precompiled code, the members of the temporary group should be individually specified in the subsystem definition.</p><br />
<br />
====Summary of file definition options====<br />
<p><br />
[[#Summary of file definition options|Subsystem file definition options]] summarizes the subsystem file definition options. </p><br />
<table><br />
<caption>Subsystem file definition options</caption><br />
<tr class="head"><br />
<th>Subsystem definition <br>option</th><br />
<th>Automatic<br />
open <br>and close?</th><br />
<th><br />
Pre-compiled <br>code?</th><br />
<th>Start/stop file <br>command allowed?</th><br />
<th>File privileges <br>assigned</th><br />
</tr><br />
<br />
<tr><br />
<td>Mandatory</td><br />
<td>Must be automatic</td><br />
<td>Yes</td><br />
<td>No</td><br />
<td>SCLASS</td><br />
</tr><br />
<br />
<tr><br />
<td>Optional</td><br />
<td>Can be automatic or manual</td><br />
<td>Yes</td><br />
<td>Yes</td><br />
<td>SCLASS</td><br />
</tr><br />
<br />
<tr><br />
<td>None</td><br />
<td>Cannot be<br />
automatic</td><br />
<td>No</td><br />
<td>Yes</td><br />
<td>File Password</td><br />
</tr><br />
</table><br />
<br />
==Subsystem processing flow==<br />
<p><br />
To design a subsystem, you must be familiar with the flow of control that occurs during subsystem processing. Subsystem processing typically involves the following phases:</p><br />
<table><br />
<tr class="head"><br />
<th>Type of processing </th><br />
<th>During this processing...</th><br />
</tr><br />
<br />
<tr><br />
<td>Initialization </td><br />
<td>Subsystem is started and an optional initialization procedure is included. </td><br />
</tr><br />
<br />
<tr><br />
<td>Login </td><br />
<td>User is logged into the subsystem; the user's privileges are determined by the subsystem definition. The appropriate required files and groups are opened for access. </td><br />
</tr><br />
<br />
<tr><br />
<td>Driver </td><br />
<td>Procedures that make up the main body of the application are included. </td><br />
</tr><br />
<br />
<tr><br />
<td>Disconnect </td><br />
<td>All files and groups are closed for the user, who is then logged out of the subsystem. </td><br />
</tr><br />
<br />
<tr><br />
<td>Error </td><br />
<td>An optional error procedure is included. The type of error that occurred is available to the error procedure. For many types of errors, the error procedure can resume normal driver processing. </td><br />
</tr><br />
</table><br />
<br />
===Initialization processing===<br />
<p><br />
Initialization processing is invoked when the subsystem is started. A subsystem is started by the START SUBSYSTEM command, or, if the start option is indicated in the subsystem definition, when the first user enters the subsystem. </p><br />
<p><br />
During subsystem initialization, <var class="product">Model&nbsp;204</var> finds the subsystem definition and opens only required subsystem files and groups. If a required file or group cannot be opened, the subsystem initialization procedure terminates and the user is returned to command level.</p><br />
<p><br />
One of the subsystem components opened during initialization is the procedure file (or group, if a multiple-procedure group has been specified). The procedure file or group must contain all of the subsystem procedures that are included by the subsystem through the communication global variable. <var class="product">Model&nbsp;204</var> scans the subsystem procedure file or group for all procedures whose names begin with either of the subsystem procedure prefixes. </p><br />
<p><br />
The subsystem initialization procedure is included at this time. This is the only time during subsystem processing that the initialization procedure is executed.</p><br />
<p><br />
If no error occurs, <var class="product">Model&nbsp;204</var> adds the subsystem name to the list of active subsystems. At this point, the subsystem is initialized and ready for use. </p><br />
<br />
===Login processing===<br />
<p><br />
Login processing is invoked when a user enters a subsystem. If the automatic login option is indicated in the subsystem definition, <var class="product">Model&nbsp;204</var> logs on the user using the subsystem name as the user ID. If the automatic login option is not indicated, the user's <var class="product">Model&nbsp;204</var> user ID remains in use. </p><br />
<p><br />
<var class="product">Model&nbsp;204</var> next finds the user's subsystem user class definition in CCASYS and opens only the required subsystem files and groups with the privileges that are found for that user class. The MSGCTL parameter automatically is set for the user according to the subsystem definition. </p><br />
<p><br />
<var class="product">Model&nbsp;204</var> sets the communication global variable to the name of subsystem login procedure and proceeds into driver processing. </p><br />
<br />
===Driver processing===<br />
<p><br />
<var class="product">Model&nbsp;204</var> determines which procedure to include next by examining the value of the communication global variable. The procedure name must be one of the names located by the scan of the procedure file during subsystem initialization. </p><br />
<p><br />
If either the global variable or the procedure name cannot be found, the subsystem's error procedure is included. If an error procedure is not specified in the subsystem definition, the user is disconnected from the subsystem. </p><br />
<p><br />
If the procedure name is found, <var class="product">Model&nbsp;204</var> determines which prefix begins the procedure name. Processing then occurs as follows:</p><br />
<ul><br />
<li>If the procedure name begins with the non-precompiled prefix, <var class="product">Model&nbsp;204</var> includes the procedure for compilation and evaluation. </li><br />
<br />
<li>If the procedure name begins with the precompiled prefix, <var class="product">Model&nbsp;204</var> verifies whether the procedure was compiled previously with the set of privileges defined by the user's subsystem user class. <br />
<p><br />
Once the compilation status of the procedure is determined, processing is as follows: </p><br />
<ul> <br />
<li>If the procedure was not previously compiled successfully for the set of privileges defined by the user's subsystem user class, <var class="product">Model&nbsp;204</var> includes the procedure for compilation and evaluation. If compilation is successful and no previous compilation was saved for the procedure, the contents of the compiler tables are saved in the system file CCATEMP.</li><br />
<br />
<li>If the procedure was previously compiled successfully for the user's privilege set, <var class="product">Model&nbsp;204</var> loads the contents of the compiler tables from CCATEMP and evaluates the request.</li><br />
</ul></li><br />
</ul><br />
<p><br />
<var class="product">Model&nbsp;204</var> repeats driver processing until the value of the communication global variable is set to the exit value specified in the subsystem definition. When the communication global variable is set to the exit value, <var class="product">Model&nbsp;204</var> proceeds into disconnect processing. </p><br />
<br />
===Disconnect processing===<br />
<p><br />
Disconnect processing is invoked when the subsystem application sets the communication variable to the exit value, when an error occurs with no subsystem error procedure, or when a subsystem user is restarted by <var class="product">Model&nbsp;204</var>. During disconnect processing, <var class="product">Model&nbsp;204</var> closes all required subsystem files and groups for the user, as well as any optional files and groups that have not been closed by the application. </p><br />
<p><br />
Depending upon whether the automatic logout option is indicated, the user is then either logged out of <var class="product">Model&nbsp;204</var> or returned to the <var class="product">Model&nbsp;204</var> command environment. </p><br />
<br />
===Error processing===<br />
<p><br />
Error processing is invoked whenever a <var class="product">Model&nbsp;204</var> error occurs that cannot be handled by the procedure being executed at the time. When an error is detected, <var class="product">Model&nbsp;204</var> sets the value of the error global variable. </p><br />
<p><br />
If the subsystem has a defined error procedure, the error procedure is included at this time. If the subsystem does not have a defined error procedure, <var class="product">Model&nbsp;204</var> proceeds into disconnect processing. </p><br />
<p><br />
If the error trapped by the subsystem is a soft restart, a hard restart, or a terminal disconnect condition, the error procedure is invoked. The communication global variable is ignored when the error procedure completes and <var class="product">Model&nbsp;204</var> proceeds with subsystem disconnect processing. </p><br />
<br />
==Parallel Query Option/204 (PQO) considerations==<br />
<p><br />
This section introduces several terms and concepts which are unique to subsystems that reference remote files and scattered groups. These concepts, and related design considerations, are discussed in greater detail in [[PQO: Scattered APSY subsystems]]. </p><br />
<br />
===Remote file access===<br />
<p><br />
Parallel Query Option/204 provides access to remote files under the Subsystem Management facility by allowing the system manager to define client and service subsystems:</p><br />
<ul><br />
<li>A client subsystem is the subsystem a user is running in when requesting access to remote data. </li><br />
<br />
<li>A service subsystem is the subsystem on a server node that a client user's service thread is logged into. <br />
</li><br />
</ul><br />
<p><br />
A service subsystem definition is stored in the CCASYS file on each node that the client subsystem accesses. The name of a subsystem must be the same at each node. The location of the client node is included in the subsystem name to uniquely identify it to the server node.</p><br />
<br />
===Node availability===<br />
<p><br />
A server node can be available or unavailable to a client subsystem.</p><br />
<ul><br />
<li>A node is available if the service subsystem has been successfully started. </li><br />
<br />
<li>If the service subsystem has not been started, it does not have a subsystem definition structure accessible to the client and is therefore unavailable. <br />
</li><br />
</ul><br />
<p><br />
A node can only be marked unavailable during start processing if there are mandatory members on a server node and the service subsystem cannot be started. If this happens, start processing also fails on the client node.</p><br />
<p><br />
Client subsystems attempting to access service subsystems that are not started receive an error message from the server node. </p><br />
<p><br />
A previously available node can become unavailable when: </p><br />
<ul><br />
<li>Resumption of communication fails after recovering from a system failure.</li><br />
<br />
<li>A user attempts to log into the service subsystem by logging into the client subsystem, the service subsystem definition is not found, and at least one mandatory member resides on that node.</li><br />
<br />
<li>A user attempts to open a file on a node where the user was not previously logged in. </li><br />
</ul><br />
<p><br />
The user is automatically logged into all associated service subsystems when entering a subsystem that contains remote files. If the service subsystem is unavailable on a node, the user cannot be logged in. </p><br />
<br />
===File and group availability===<br />
<p><br />
The members of a subsystem are files and permanent groups. With Parallel Query Option/204, members can be either automatic or manual: </p><br />
<ul><br />
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li><br />
<br />
<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command. <br />
</li><br />
</ul><br />
<p><br />
Members can also be either mandatory or optional:</p><br />
<ul><br />
<li>A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual.</li><br />
<br />
<li>An optional member is not required for subsystem access (start and login processing can succeed without it). <br />
</li><br />
</ul><br />
<p><br />
At any given time a member can be open or closed to a subsystem or to a user within a subsystem. The following sections explain the conditions under which the different kinds of members are accessible to APSY subsystems and their users.</p><br />
<br />
====Member availability to subsystems====<br />
<p><br />
Automatic members of subsystems are always opened by the START SUBSYSTEM command or by SUBSYSTEM LOGIN. At the end of START processing, each automatic member is open unless either the START or OPEN failed. </p><br />
<p><br />
Manual members of subsystems are in the closed state at the completion of START SUBSYSTEM processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If OPEN fails due to node unavailability or for user-specific reasons (for example, if the user's line goes down) the member remains closed to the subsystem.</p><br />
<p><br />
If a node becomes unavailable to a subsystem, all automatic subsystem members and all open manual subsystem members residing on the unavailable node are marked disabled.</p><br />
<p><br />
If a STOP FILE/GROUP command is issued for a manual member on the client subsystem's node, the member is closed to the client subsystem when the last user closes it. If the member is located on the service subsystem node, the file is closed to the service subsystem when the STOP is complete or the last user closes the file.</p><br />
<br />
====Member availability to subsystem users====<br />
<p><br />
When a user enters a subsystem, automatic subsystem members are opened.</p><br />
<p><br />
If a user LOGIN or OPEN operation fails for an optional member, the member is left closed for the user but remains available to the subsystem. If a mandatory member cannot be opened, the user is denied access to the subsystem.</p><br />
<p><br />
If a user LOGIN or OPEN operation fails for an already open member, the member is left disabled for the user but remains open to the subsystem. </p><br />
<p><br />
If an automatic mandatory member is closed to the subsystem, new users are not allowed to enter the subsystem.</p><br />
<p><br />
Manual members of subsystems are closed for a user within a subsystem until the user issues an OPEN command or statement. In this case it does not matter whether the member is open or closed to the subsystem.</p><br />
<p><br />
If compilation and/or loading of a request fails due to a communications failure, previously opened members on the failing node become disabled to the user. </p><br />
<p><br />
A user can close optional members at any time by issuing the CLOSE command.</p><br />
<br />
====Enabling disabled subsystem files====<br />
<p><br />
In the event that a subsystem file or group is marked disabled, you can enable it (after correcting the problem) without having to bring the subsystem down. To do this, use the ENABLE SUBSYSTEM command:</p><br />
<br />
====Syntax====<br />
<p class="syntax">ENABLE SUBSYSTEM <span class="term">subsysname</span> <br />
[FILE <span class="term">name</span> AT <span class="term">location</span> <span class="squareb">|</span> GROUP <span class="term">name</span>]<br />
</p><br />
Where:<br />
<ul><br />
<li><var class="term">subsysname</var> is the name of the client subsystem</li><br />
<br />
<li><var class="term">location</var> is the name of the remote node where the file is stored. Note that the location must be explicitly specified; you cannot reference local files with the ENABLE SUBSYSTEM command. <br />
</li><br />
</ul><br />
<br />
====Intentionally disabling a subsystem file====<br />
<p><br />
You can make a subsystem file or group (or an entire subsystem, if a file is mandatory) temporarily inaccessible without having to bring the subsystem down, using the DISABLE SUBSYSTEM command:</p><br />
<p class="syntax">DISABLE SUBSYSTEM <span class="term">subsysname</span> <br />
[FILE <span class="term">name</span> AT <span class="term">location</span> <span class="squareb">|</span> GROUP <span class="term">name</span>]<br />
</p><br />
<p><br />
When a file or group is intentionally disabled with the DISABLE SUBSYSTEM command, subsystem behavior is exactly the same as when a communications failure causes the disabling. This behavior is described in [[#File and group availability|File and group availability]].</p><br />
<br />
===Trust===<br />
<p><br />
As an alternative to the privilege settings normally available through the Subsystem Management facility, the system manager at a service node can control client subsystem access by creating a trust definition for the client subsystem. If a client subsystem is fully or partially trusted, the trust definition is sufficient for maintaining the relationship with the client; the system manager at the service node does not have to create and maintain a separate set of file and SCLASS definitions for the client subsystem.</p><br />
<p><br />
For example, suppose a subsystem located on a node named DETROIT (the client node) includes in its definition files located on a node named CLEVELAND (the service node). Further, suppose the subsystem is fully or partially trusted by CLEVELAND. In this case, the file and SCLASS definitions are maintained only on the client node (DETROIT), and the service node (CLEVELAND) needs only to maintain the trust definition.</p><br />
<p><br />
The four levels of trust available with Parallel Query Option/204 are:</p><br />
<ul><br />
<li><b>Full trust</b><br />
<p><br />
Only the subsystem name and location appear on the service node's definition, which you create on the Subsystem Trust screen.</p></li><br />
<br />
<li><b>Partial trust</b><br />
<p><br />
Along with the subsystem name and location, you can specify maximum file privileges. In this case, the client subsystem is trusted, but the maximum file privileges and field level security levels specified on the Subsystem Trust screen cannot be exceeded.</p><br />
<ul><br />
<li>If a user requests file privileges that would exceed the maximum, the service node does not open the file to that user.</li><br />
<li>If a user requests a field level security status that would exceed the maximum, <var class="product">Model&nbsp;204</var> automatically resets the request to the allowed level (that is, the maximum) and opens the file to that user.</li><br />
</ul></li><br />
<br />
<li><b>Restricted trust</b><br />
<p><br />
For a subsystem that has a restricted trust definition, you make no entries on the Subsystem Trust screen. A restricted trust definition is based solely on entries you make on these five screens:</p> <br />
<ul><br />
<li>Subsystem Activity</li><br />
<li>Subsystem File Use</li><br />
<li>Operational Parameters</li><br />
<li>Subsystem Classes</li><br />
<li>Subsystem Class Users</li><br />
</ul><br />
<p><br />
The accessibility of service node files to a client subsystem is determined by the SCLASS, user, and file privileges that you specify on these screens. </p><br />
</li><br />
<br />
<li><b>No trust</b><br />
<p><br />
No subsystem service definition exists for the subsystem. The client subsystem cannot access any files on the service node as subsystem files. The files on the service node can, however, be accessed from within a client subsystem as individual, non-subsystem files if the following criteria are met:</p><br />
<ul><br />
<li>Parallel Query Option/204 is installed at both sites.</li><br />
<li>Horizon is installed at both sites, and there are link, processgroup, and process definitions connecting the client node to the service node.</li><br />
<li>For any given file, the value of the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter allows remote access (X'02', X'04', or X'08'). </li><br />
</ul><br />
</li><br />
</ul><br />
<p><br />
See the<br />
<var class="book">Rocket Parallel Query Option/204 User's Guide</var> for detailed information on creating and managing trust definitions.</p><br />
<br />
==Subsystem design considerations==<br />
<p><br />
This section presents coding considerations for subsystem procedures. Some of the guidelines listed below also appear in earlier sections. They are consolidated here for the convenience of the application developer. </p><br />
<br />
===Coding considerations===<br />
<ul><br />
<li>Procedures should be small and modular.</li><br />
<br />
<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li><br />
<br />
<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li><br />
<br />
<li>The communication global variable must be set to the exit value in order to exit the subsystem. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used.</li><br />
<br />
<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li><br />
<br />
<li>Non-subsystem files can be opened and referenced only by non-precompiled procedures.</li><br />
<br />
<li>Precompiled procedures cannot reference PERM groups that are not members of the same subsystem.</li><br />
<br />
<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li><br />
<br />
<li>The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. </li><br />
<br />
<li>Distinct group numbers are assigned to optional groups at START SUBSYSTEM time. Those numbers cannot be used by non-subsystem members opened within the subsystem. Thus the NGROUP limit used for earlier releases might be exceeded during either START or OPEN processing inside the subsystem.</li><br />
<br />
<li>To prevent you from having the wrong file or group privileges in a subsystem, <var class="product">Model&nbsp;204</var> closes optional files and groups before entering a subsystem. In earlier releases, optional files and groups were only closed when you left the subsystem. <br />
</li><br />
</ul><br />
<p><br />
Users should be aware of the following conditions when coding applications to run under the Subsystem Management facility:</p><br />
<ul><br />
<li>Dummy strings (??, ?$, ?&amp;) in precompiled procedures are resolved only during compilation for the first user.</li><br />
<br />
<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li><br />
<br />
<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li><br />
<br />
<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li><br />
<br />
<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed. <br />
<p><br />
The default action for each type of message is listed in [[M204.1076]]. </p><br />
<p><br />
If you do not wish the default action to be executed, you need to add a message handler routine to the procedure containing the statement that invokes the message. </p><br />
</li><br />
</ul><br />
<br />
====Keeping track of the number of files referenced====<br />
<p><br />
To keep track of the files referenced in a subsystem procedure, which cannot exceed 6,043 files &mdash; a CCATEMP page, use the following formula:</p><br />
<p class="code">NFILE + NRFILE + 1 (for CCAGRP) + 1 (for CCASYS)<br />
</p><br />
<br />
==Record locking considerations==<br />
<p><br />
Depending upon the subsystem definition, <var class="product">Model&nbsp;204</var> might place a share lock on one or more subsystem procedure names or group names. </p><br />
<p><br />
If the subsystem is defined with permanent groups, <var class="product">Model&nbsp;204</var> locks the group names to ensure that the group definitions do not change while the subsystem is running. A share lock is maintained for each group while the subsystem is active. </p><br />
<br />
===If subsystem files are defined as unlocked===<br />
<p><br />
If the subsystem definition specifies that subsystem files are unlocked, <var class="product">Model&nbsp;204</var> locks in share mode each of the subsystem procedures to ensure that the procedures do not change or move. This prevents any user from:</p><br />
<ul><br />
<li>Issuing the DELETE PROCEDURE command</li><br />
<br />
<li>Issuing the RENAME PROCEDURE command</li><br />
<br />
<li>Updating the procedure while the subsystem is active. <br />
</li><br />
</ul><br />
<br />
==Subsystem procedure control functions==<br />
<p><br />
The User Language functions, [[$Sclass#$Sclass|$Sclass]] and [[$Subsys#$Subsys|$Subsys]] can be useful in determining subsystem program control.</p><br />
<br />
===$Sclass function===<br />
<p><br />
The $Sclass function returns the Sclass name of the current user. $Sclass is useful when the transfer of control is dependent upon a user's privileges. For example:</p><br />
<p class="code"> BRANCH: JUMP TO (ADD.REC, VIEW.REC, UPD.REC) -<br />
%MAIN.MENU:SELECTION<br />
.<br />
.<br />
.<br />
UPD.REC: IF $sclass = 'READ' THEN<br />
IF $SETG('NEXT','PRE-RPT.PGM') THEN<br />
PRINT 'GLOBAL TABLE FULL'<br />
END IF<br />
ELSEIF $sclass = 'UPDATE' THEN<br />
IF $setg('NEXT','PRE-MAINT.PGM') THEN<br />
PRINT 'GLOBAL TABLE FULL'<br />
END IF<br />
.<br />
.<br />
.<br />
</p><br />
<br />
===$Subsys function===<br />
<p><br />
The $Subsys function returns a numeric value indicating the status of a subsystem, or the name of the current subsystem (if no argument is specified). $Subsys often is used to determine whether a subsystem is active before a transfer is attempted. </p><br />
<br />
==Subsystem development tools==<br />
<p><br />
This section describes three <var class="product">Model&nbsp;204</var> features that are useful in developing, testing and debugging subsystem procedures:</p><br />
<ul><br />
<li>The <var>[[DEBUG command|DEBUG]]</var> and <var>[[TEST command|TEST]]</var> commands, which assist subsystem debugging by allowing you to display the global communications variable and specify the next procedure to be INCLUDEd.</li><br />
<br />
<li>Multiple procedure file groups, which allow users to change procedures without stopping the subsystem or interfering with other users.</li><br />
<br />
<li>The Cross-Reference facility, which produces reports on the variable names, global dummy strings, and other language elements used in a specified set of User Language procedures. </li><br />
</ul><br />
<br />
===Debugging and testing facilities===<br />
<p><br />
The <var class="product">Model&nbsp;204</var> DEBUG and TEST SUBSYSTEM commands assist you in debugging subsystem code while it is being developed. Both commands display the value of the communication global variable, prompt you for changes, and display since-last statistics. </p><br />
<p><br />
DEBUG differs from TEST SUBSYSTEM in the following ways:</p><br />
<ul><br />
<li>DEBUG can be executed by more than one user in the same subsystem at the same time; TEST SUBSYSTEM can only be executed by a single user.</li><br />
<br />
<li>To execute TEST SUBSYSTEM, the user must stop the subsystem, which will be restarted in single user mode as a result of issuing the TEST command. To execute DEBUG, the user does not have to stop the subsystem. The DEBUG command can be issued for any subsystem that has been started, or for any subsystem that has the AUTOSTART feature.</li><br />
<br />
<li>Since-last statistics are provided automatically with DEBUG; they are optional with TEST. <br />
</li><br />
</ul><br />
<p><br />
In general, the DEBUG command is more convenient for subsystem developers in a multiuser environment.</p><br />
<p><br />
To execute the DEBUG command, the user must be named to an SCLASS which has been granted either the TEST or DEBUG privilege. The DEBUG privilege does not entitle the user to execute the TEST command.</p><br />
<br />
====Syntax====<br />
<p><br />
The format of the DEBUG command is: </p><br />
<p class="syntax">DEBUG SUBSYSTEM <span class="term">subsystemname</span> [<span class="term">parameters</span>]<br />
</p><br />
<p><br />
The extended format of the TEST command is:</p><br />
<p class="syntax">TEST [DEBUG] [STATS] [SUBSYSTEM] <span class="term">subsystemname</span> <span class="term">parameters</span><br />
</p><br />
Where:<br />
<ul><br />
<li>DEBUG specifies that the communication global variable is displayed on the user's terminal before the next procedure is included. The user then has the option of specifying a different procedure to be included next. If the user presses <var>ENTER</var> without specifying a different procedure, the procedure whose name is currently displayed is included next. </li><br />
<br />
<li>STATS specifies that since-last statistics are displayed on the user's terminal after each procedure is evaluated. Since-last statistics are described in [[Using system statistics#User since-last statistics|User since-last statistics]]. </li><br />
<br />
<li>SUBSYSTEM specifies that the word following the keyword is the name of a subsystem and that parameters follow the subsystem name. This keyword can be used to eliminate confusion when DEBUG or STATS is the name of a subsystem or subsystem parameter. </li><br />
<br />
<li><i>parameters</i> specifies the parameters to be stored in the command line global variable. The parameter information can be as many as 255 characters in length. <br />
</li><br />
</ul><br />
<br />
===Multiple procedure files===<br />
<p><br />
If <code>PROCFILE=*</code> is specified when a group is created, then several files in a group can contain procedures. When the <var>INCLUDE</var> command is executed in the context of a multiple procedure file group, files are searched, left to right, in the order they were defined in the original <var>CREATE GROUP</var> command.</p><br />
<p><br />
Multiple procedure file groups make it possible to change subsystem procedures without having to stop the subsystem. This is accomplished by setting <b>GROUP</b> to <code>Y</code> for the subsystem's procedure file in the subsystem definition, and by specifying a number value for <b>Procs NUMLK</b> that is less than the number of files in the group. The application subsystem locks the procedures in the last (or rightmost) NUMLK number of files, as determined by the right-to-left order they were specified in the <var>CREATE GROUP</var> command that defined the procedure group. For an example, see [[System requirements for Application Subsystems#Subsystem File Use screen|Subsystem File Use screen]].</p><br />
<p><br />
The multiple procedure file option also allows different users to make changes to procedures in the same subsystem without interfering with each other. The procedure group specified in the subsystem definition must have a corresponding <var>CREATE PERM GROUP</var> definition. However, any individual user can create or open a temporary group with the same name as the subsystem's permanent procedure group. If a user has such a temporary group open and enters a subsystem, the subsystem uses the temporary group instead of the subsystem's permanent group. </p><br />
<p><br />
The following restrictions apply to the use of temporary groups to store subsystem procedure files:</p><br />
<ul><br />
<li>The user's SCLASS must have the <var>TEST</var> or <var>DEBUG</var> privilege.</li><br />
<br />
<li>The last <i>n</i> files of the <var>CREATE PERM GROUP</var> command (where <i>n</i> is set by the <code>NUMLK</code> parameter) must correspond exactly to the last <i>n</i> files of the <var>CREATE TEMP GROUP</var> command. </li><br />
</ul><br />
<br />
===Cross-Reference facility===<br />
<p><br />
The Cross-Reference facility is a Dictionary facility that can be invoked from both the Dictionary Main Menu and <var class="product">Model&nbsp;204</var> command level. It produces reports for users who develop and maintain <var class="product">Model&nbsp;204</var> User Language procedures.</p><br />
<p><br />
The output reports show the line numbers where language elements such as labels, functions, images and variable names occur in a specified set of procedures. Elements within subroutines and nested INCLUDEs can also be cross-referenced.</p><br />
<p><br />
The Cross-Reference Report is produced in batch mode (by a batch job in OS and DOS, by a service machine in CMS). Prior to submitting a cross-reference job, the user can specify:</p><br />
<ul><br />
<li>A set of procedures in a procedure file or group</li><br />
<br />
<li>A set of language elements to be cross referenced</li><br />
<br />
<li>Substitute values for User Language global dummy strings</li><br />
<br />
<li>Job-related parameters such as output destination and lines per page <br />
</li><br />
</ul><br />
<p><br />
The Cross-Reference facility also includes Preview and Browse functions, which inform the user about the procedures selected for processing.</p><br />
<p><br />
For a complete description of the Cross-Reference facility, refer to the [[:Category:Dictionary/204#Dictionary/204 topics|Dictionary/204 topics]].</p><br />
<br />
[[Category:SOUL]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=LVTBL_parameter&diff=116742LVTBL parameter2018-08-21T23:08:20Z<p>JAL: add link</p>
<hr />
<div>{{Template:LVTBL parameter subtitle}}<br />
==Summary==<br />
<dl><br />
<dt>Default value<br />
<dd>50<br />
<dt>Parameter type<br />
<dd>Utable<br />
<dt>Where set<br />
<dd>On user's parameter line or reset by <var>[[UTABLE_command|UTABLE]]</var> command<br />
<dt>Related products<br />
<dd>All<br />
<dt>Introduced<br />
<dd><var class="product">Model 204 V2.2</var> or earlier<br />
</dl><br />
<br />
==Description==<br />
<p><br />
<var>LVTBL</var> specifies the number of 32-byte entries in the table of compiler variables, [[VTBL]]. </p><br />
<p><br />
<var>LVTBL</var> can range from 5 to 524287. For an [[Application Subsystem development|application subsystem]] user, <var>LVTBL</var> must have a minimum value of 50. <br />
</p><br />
<br />
[[Category:Utable parameters]]<br />
[[Category:Parameters]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=VTBL&diff=116741VTBL2018-08-21T22:55:27Z<p>JAL: Redirected page to Large request considerations#VTBL (compiler variable table)</p>
<hr />
<div>#REDIRECT [[Large request considerations#VTBL (compiler variable table)]]</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.3027&diff=116737M204.30272018-08-20T18:12:32Z<p>JAL: add info from 7.6 rel notes</p>
<hr />
<div>{{Template:M204.3027 skeleton}}<br />
__NOTOC__<br />
<p><br />
This message accompanies message [[M204.2027]] which reports the rejection of an attachment request. M204.3027 displays the remote ID from which the attach request was made. </p><br />
<p><br />
<b>System manager response:</b> <br />
Use the information in this message to identify the issuer of the rejected attach request. </p><br />
<p><br />
<b>Version introduced:</b><br />
7.7 (available in 7.6 with zap maintenance applied)<br />
</p><br />
{{Template:M204.3027 footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.2955&diff=116736M204.29552018-08-20T18:11:08Z<p>JAL: wordsmithing</p>
<hr />
<div>{{Template:M204.2955 skeleton}}<br />
__NOTOC__<br />
<p><br />
There is not enough storage to allocate the universal buffer. The request has been cancelled. </p><br />
<p><br />
<b>System manager response:</b> Correct and retry.<br />
</p><br />
<p><b>Version introduced:</b><br />
7.7 (displays in 7.5 and 7.6 instead of a bug, with appropriate zap maintenance applied)<br />
</p><br />
{{Template:M204.2955 footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.3026&diff=116735M204.30262018-08-20T18:06:59Z<p>JAL: add info from 7.6 rel notes</p>
<hr />
<div>{{Template:M204.3026 skeleton}}<br />
__NOTOC__<br />
<p><br />
This message accompanies message [[M204.2027]] which reports the rejection of an attachment request. M204.3026 displays the transaction program requested by the attach, as well as the user ID associated with that request. </p><br />
<p><br />
<b>System manager response:</b><br />
Use the information in this message to identify the issuer of the rejected attach request. <br />
</p><br />
<p><br />
<b>Version introduced:</b><br />
7.7 (available in 7.6 with zap maintenance applied)<br />
</p><br />
{{Template:M204.3026 footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.2958&diff=116734M204.29582018-08-20T18:03:19Z<p>JAL: add info from rel notes</p>
<hr />
<div>{{Template:M204.2958 skeleton}}<br />
__NOTOC__<br />
<p><br />
Under Model&nbsp;204 version 7.6, the <var>APSYPAGE</var> parameter is disabled; if it is set, the Online will still come up. However, <var>APSYPAGE</var> will have no effect. </p><br />
<p><br />
Under version 7.7, setting <var>APSYPAGE</var> to a non-zero value results in an error and prevents the Online from coming up. </p><br />
<p><br />
<b>Response:</b> Set <var>APSYPAGE</var> to 0, and use an alternative (see [[APSYPAGE parameter]] for information about an alternative). <br />
</p><br />
<p><b>Version introduced:</b><br />
7.6<br />
</p><br />
{{Template:M204.2958 footer}}</div>JALhttps://m204wiki.rocketsoftware.com/index.php?title=M204.2954&diff=116733M204.29542018-08-20T17:50:55Z<p>JAL: add info from 7.6 rel notes</p>
<hr />
<div>{{Template:M204.2954 skeleton}}<br />
__NOTOC__<br />
<p><br />
This informational message indicates that the named feature is not supported for zHPF. </p><br />
<p><br />
<b>Response:</b> No response is needed. This message is for information only. </p><br />
<p><br />
<b>Version introduced:</b><br />
7.6<br />
</p><br />
{{Template:M204.2954 footer}}</div>JAL