.. _tn201522: What’s new in Virtel 4.55 ========================= The following newsletter discusses some of the new features that are available in Virtel Release 4.55. **CICS QUICKLNK support for multiple CHANNEL and CONTAINER names** Quicklink support has been enhanced to allow multiple channels and contains. QuickLink is a protocol used in support of Syspertec’s Virtel Transaction Gateway (VTG) product which is an alternative to IBM’s CTG solution. :: OPTION$ FOR-QUICKLNK, (METHOD,'CALL-CONTAINER-LIST'), (PROGRAM,'*TARGET'), (CONTAINERS-FOR-QUESTION,'DATAIN'), (CONTAINERS-FOR-RESPONSE,'DATAOUT'), (CHANNEL,'*MYCHANNEL'), (TERMINAL,'CICS-TERMINAL'), (RET-CODE,'RETURN-CODE'), (RET-CICS1,'EIBRESP'), (RET-CICS2,'EIBRESP2'), TOVAR='MYPARMS' **Improved SCREEN-PROCESSING facility** This modification introduces a new screen processing facility by allowing you to SET$ a SCREEN-POSITION, advancing the SCREEN-POSITION, CASE$ for a SCREEN-POSITION and COPY$ to/from a SCREEN-POSITION. Example: Setting a screen position. (hh equals the number of lines in the column) :: SET$ SCREEN-POSITION,(lig,col,len,hh) Advancing the position to next line: :: SET$ SCREEN-POSITION,TO-NEXT-LINE If the next line is after the end of the current screen rectangle, it wraps to back to the beginning. This condition may be tested with: :: IF$ NOT-FOUND,THEN=... CASE$ which works with the current screen position: CASE$ CURRENT-SCREEN-POSITION,(EQ,'XXXX',ET1),... CASE$ which works with current screen line, column, length, equal sign and hard coded column and length:- :: CASE$ (=,COL,LEN),(EQ,'XXXX',ET1),... COPY$ which works with current screen line, column, length, equal sign: COPY$ VARIABLE-TO-SCREEN,VAR='VAR1',SCREEN=(=,col,len) **Support for MAP$ JSON input.** Support is added to JSON format to be copied into a commarea. This complements the existing XML and QUERY data currently supported by the MAP$ statement. :: COMMAREA MAP$ FROM-VARIABLE,XML,VAR='MYINPUT' default COMMAREA MAP$ FROM-VARIABLE,QUERY,VAR='MYINPUT' COMMAREA MAP$ FROM-VARIABLE,JSON,VAR='MYINPUT' Other supported MAP$ structures:- :: COMMAREA MAP$ FROM-INPUT,JSON (Input is in json format) COMMAREA MAP$ FROM-INPUT,JSON,FIELD='MYINPUT' **New toolbar button to toggle the 3278T mode on/off.** The 3278T button is hidden by default but can now be shown by selecting options in the user settings dialog. **New UNLOAD command to unload ARBO.** Following the performance improvements through the introduction of VSAM LSR the VIRCONF program was no longer able to access the ARBO VSAM file when VIRTEL was running. To compensate for this a new UNLOAD command has been added to VIRTEL which performs an ARBO UNLOAD. Example: :: F virtel,unload This command invokes the VIRCONF program which unloads the ARBO file. The following DD statement must be added to the Virtel procedure:- :: //SYSPUNCH DD DSN=SP000.VIRTELxx.VIRCONF.SYSIN,DISP=(,CATLG), // UNIT=SYSDA,VOL=SER=VVVVVV,SPACE=(TRK,(5,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6080) Or alternatively:- :: //SYSPUNCH DD SYSOUT=B **Customization of the Virtel toolbar** The toolbar elements can now be controlled through a user custom.js Javascript element. An example is provided below. Sample customization code[in custom.js]: :: /* * Customize the location of dynamic toolbar buttons. * The calls to this function are ignored when they * return nothing, or an integer not greater than 0. * * Customizable buttons IDs : * > '3278T' * > 'document-print-preview' * > 'file-send' * > 'file-recv' * > 'printer' */ function customize_toolbarButtonIndex(id) { if (id==='printer' || id==='document-print-preview') { return getToolbarButtonIndex('disconnect') + 1; } } **NEW MAP$ FROM-INPUT TO-VARIABLES parameter** The MAP$ FROM-INPUT statement now has a new TO-VARIABLES parameter. This enables conversion of input directly to output variables without the need to go through an intermediate commarea. Before you had to use three statements:- :: JSONAF1 MAP$ FROM-INPUT,JSON,FIELD='MYINPUT' generate commarea JSONAF1 MAP$ TO-VARIABLE,VAR='MYCRBO00' copy commarea to variable JSONAF1 TOVAR$ FROM-VARIABLE,VAR='MYCRBO00' generate variables This would convert the JSON input to variables with the names specified in the JSONAF1 MAP$. Now, the similar conversion can be achieved with just one statement:- :: JSONAF1 MAP$ FROM-INPUT,JSON,TO-VARIABLES,FIELD='MYINPUT' generate variables .. note:: This new form of the instruction alleviates the need for an OCCURS=UNLIMITED at the end of a description. **Allow re-execution of a MAP$ FROM-INPUT** In the following scenario, the two 'MAP$ FROM-INPUT' will produce the same output. Example:- :: JSON1 SCREENS APPL=JSON1 * SCENARIO INITIAL * SET$ ENCODING,UTF-8,'IBM1147' JSONAF1 MAP$ BEGIN MAP$ AREA,WITH='inAFR',LENGTH=30 MAP$ AREA,WITH='inICT',LENGTH=30 * INSUBFS MAP$ BEGIN,WITH='friends' INSUBF MAP$ BEGIN,WITH=NEXT-ELEMENT,OCCURS=UNLIMITED MAP$ AREA,WITH='inRRN',LENGTH=17 MAP$ AREA,WITH='inQtyT10',LENGTH=10,TYPE=9 INSUBF MAP$ END INSUBFS MAP$ END JSONAF1 MAP$ END * JSONAF1 MAP$ FROM-INPUT,JSON,TO-VARIABLES,FIELD='MYINPUT' ERROR$ 0,'COUNT=','*INSUBF' DEBUG$ SNAP,TERMINAL PERFORM$ DECODE * JSONAF1 MAP$ FROM-INPUT,JSON,TO-VARIABLES,FIELD='MYINPUT' ERROR$ 0,'COUNT=','*INSUBF' DEBUG$ SNAP,TERMINAL PERFORM$ DECODE * SCENARIO END * DECODE SCENARIO SUBROUTINE DECODELOOP LABEL$ IF$ NOT-EXISTS-VARIABLE,'inRRN',THEN=THEEND ERROR$ 0,'inRRN=','*inRRN' ERROR$ 0,'inQtyT10=','*inQtyT10' POP$ FIRST-VALUE-OF,VAR='inRRN' POP$ FIRST-VALUE-OF,VAR='inQtyT10' GOTO$ DECODELOOP THEEND LABEL$ SCENARIO END * SCRNEND END , **New trimming functions. CASE$ RTRIM and LTRIM / EMPTY** Two new optional parameters for the CASE$ instruction, RTRIM= and LTRIM=, allow the removal of one or more characters from the various operands of the CASE$ instruction before the comparisons are done. Also, a new CASE$ condition EMPTY is added to allow testing whether a variable or a part of the screen buffer is empty. The empty condition can be tested after the variable or screen has been trimmed. Examples:- :: CASE$ 'MYVAR', * (EMPTY,L2), * (CONTAINS,'*Val',L1) * RTRIM=('_',' '), * LTRIM=('_',' '), * ELSE=other * CASE$ (1,1,80), * (CONTAINS,'Val',L1),RTRIM=('_',' ') .. note:: 1: CASE$ do not change the contents of the variables or parts of the screen being compared. 2: If the variable being tested does not exist, (eg 'MYVAR' does not exist), it is not considered empty. Rather, the CASE$ branches at the ELSE= label. LTRIM and RTRIM will trim both the value being tested (variable or part of the screen buffer) and the variable arguments, but not the static arguments. For example:- (EQ,'\*VAR1',label1) The value of the VAR1 variable will be trimmed prior to comparison. (EQ,'zagreb ',label2) The value of the string 'zagreb ' will NOT be trimmed – it is a static argument. **New trimming functions. COPY$ RTRIM and LTRIM** Two new optional parameters for the COPY$ LIST-TO-VARIABLE instruction, RTRIM= and LTRIM=, will trim one or more characters from the various variable operands of the COPY$ instruction prior to performing the copy. Example:- :: COPY$ LIST-TO-VARIABLE,VAR='VAR1', * RTRIM=('_',' '),LTRIM=('_',' '), * LIST=('string1','*var1',VARIABLE,'var2') The variable VAR1 is created/modified, with 'string1' copied as is, var1 and var2 left and right trimmed. **Indirection on OUTPUT-FILE-TO-VARIABLE FILE=** This feature allows indirection of a file name. The filename is pointed to by the variable \*variable_name. Example:- :: COPY$ OUTPUT-FILE-TO-VARIABLE,FILE='*MYFILE',VAR='MYRESULT' **COPY$ VARIABLE-TO-VARIABLE** Copies a source variable to a target variable. VAR= must specifies two variable names, the first being the source, the second the target. TYPE=REP may be specified to mean the target variable should be replaced. Otherwise the new value is appended the target variable. OFFSET= is the number of characters to skip in the string, defaulting to 0. LENGTH= is how many characters to copy, defaulting to the remainder of the string from start. If length is longer than the string, padding occurs with the PAD= character. This defaults to the blank. Example:- :: COPY$ VARIABLE-TO-VARIABLE, * VAR=('VAR1','VAR2'), * OFFSET=8,LENGTH=5,PAD=' ' **COPY$ CURRENT-LINE enhancement** This update complements the CASES$ CURRENT-SCREEN POSITION feature. It allows copying of current values of the field in the SCREEN-POSITION to a variable. The length of the returned value may be specified with the LENGTH= parameter. Examples:- :: SET$ SCREEN-POSITION,(10,20,5,15) SET$ SCREEN-POSITION,TO-NEXT-LINE COPY$ SYSTEM-TO-VARIABLE,VAR='L1',LENGTH=2, * FIELD=(VALUE-OF,CURRENT-LINE) COPY$ SYSTEM-TO-VARIABLE,VAR='C1',LENGTH=2, * FIELD=(VALUE-OF,CURRENT-COLUMN) COPY$ SYSTEM-TO-VARIABLE,VAR='L2', * FIELD=(VALUE-OF,CURRENT-LENGTH) COPY$ SYSTEM-TO-VARIABLE,VAR='H1', * FIELD=(VALUE-OF,CURRENT-HEIGHT) **Virtel Memory Display** The Memory display feature is a memory diagnostic tool created to trap possible invalid Virtel memory free requests. Such request can lead to ABEND0C4s and other unwanted behaviour. Virtel memory requests (PRENDRE and RENDRE) are tracked in a diagnostic storage area located above the bar. The area is 1MB in size and can contain 65536 active storage requests. An active storage request is a storage area that has been gotten (PRENDRE) and is pending a Virtel storage release (RENDRE). This diagnostic tool should only be used when recommended by Technical Support. The feature is supported by the following command:- :: F VIRTEL,MEMDISPLAY This produces a breakdown of the internal VIRTEL subpools. See the following command response:- :: F SPTHOLTV,MEMDISPLAY VIR0200I MEMDISPLAY VIR0271I DISPLAY 763 SP1=00024478 SP2=00000CCC SP3=00090DE0 SP4=000027E4 00910091 00030009 02430294 00090011 SP5=00029293 SP6=0004DCF4 SP7=00000000 SP8=00000000 00A404C7 01370137 00000000 00000002 POOL CONTROL BLOCK. SUBPOOL=1 PAG=00108000 NFQ=00108008 #FQ=00000001 FRE=0000B2A0 PAG=000F8000 NFQ=000F8008 #FQ=00000001 FRE=00000080 PAG=000E8000 NFQ=000E8008 #FQ=00000001 FRE=00000078 POOL CONTROL BLOCK. SUBPOOL=2 PAG=1EC14000 NFQ=1EC14008 #FQ=00000004 FRE=0000F2F0 POOL CONTROL BLOCK. SUBPOOL=3 PAG=1ECC4000 NFQ=1ECC4008 #FQ=00000002 FRE=00006408 PAG=1ED54000 NFQ=1ED54008 #FQ=00000002 FRE=00001750 PAG=1EC74000 NFQ=1EC74008 #FQ=00000001 FRE=00000878 PAG=1ED04000 NFQ=1ED04008 #FQ=00000001 FRE=00000878 PAG=1ED94000 NFQ=1ED94008 #FQ=00000002 FRE=00002768 PAG=1ECF4000 NFQ=1ECF4008 #FQ=00000002 FRE=000017F0 PAG=1EE04000 NFQ=1EE04008 #FQ=00000001 FRE=00000878 PAG=1ED74000 NFQ=1ED74008 #FQ=00000001 FRE=00000878 PAG=1ECE4000 NFQ=1ECE4008 #FQ=00000001 FRE=00000878 PAG=1EC64000 NFQ=1EC64008 #FQ=00000001 FRE=00000878 POOL CONTROL BLOCK. SUBPOOL=4 PAG=1EC04000 NFQ=1EC04008 #FQ=00000003 FRE=0000D750 POOL CONTROL BLOCK. SUBPOOL=5 PAG=1ED24000 NFQ=1ED24008 #FQ=00000001 FRE=0000A1D8 PAG=1ED14000 NFQ=1ED14008 #FQ=00000001 FRE=000043B8 PAG=1EC54000 NFQ=1EC54008 #FQ=00000001 FRE=000043B8 PAG=1EBB4000 NFQ=1EBB4008 #FQ=00000001 FRE=000043B8 POOL CONTROL BLOCK. SUBPOOL=6 PAG=1EBF4000 NFQ=1EBF4008 #FQ=00000003 FRE=00000D40 PAG=1EBE4000 NFQ=1EBE4008 #FQ=00000001 FRE=00000088 PAG=1EBD4000 NFQ=1EBD4008 #FQ=00000001 FRE=000000B8 PAG=1EBC4000 NFQ=1EBC4008 #FQ=00000001 FRE=000000D0 PAG=1EBA4000 NFQ=1EBA4008 #FQ=00000001 FRE=00000108 POOL CONTROL BLOCK. SUBPOOL=7 PAG=00000000 NFQ=00000000 #FQ=00000000 FRE=00000000 POOL CONTROL BLOCK. SUBPOOL=8 PAG=00000000 NFQ=00000000 #FQ=00000000 FRE=00000000 ALLOC=0001213K, FREE=0000314K, TOTAL=0001536K VIR0272I END **Enablement/Dis-enablement** The memory diagnostic tool is only activated through the following TCT parameter :: MEMORY=(ABOVE,MEMHST), The memory diagnostic tool can be deactivated by the following command:- :: F VIRTEL,MEMDISPLAY,DISABLE *Operation* With the memory diagnostic tool active the following command be used to summarize the VIRTEL subpool active allocated memory:- :: F VIRTEL,MEMDISPLAY The following will be displayed:- :: F SPTHOLTV,MEMDISPLAY VIR0200I MEMDISPLAY VIR0271I DISPLAY 978 SP1=00024478 SP2=00001044 SP3=0008E35F SP4=00002F61 00910091 00040009 02380294 000B0011 SP5=000317DC SP6=0004DF73 SP7=00000000 SP8=00000220 00C504C7 01370137 00000000 00000002 POOL CONTROL BLOCK. SUBPOOL=1 PAG=00109000 NFQ=00109008 #FQ=00000001 FRE=0000B2A0 PAG=000F9000 NFQ=000F9008 #FQ=00000001 FRE=00000080 PAG=000E9000 NFQ=000E9008 #FQ=00000001 FRE=00000078 POOL CONTROL BLOCK. SUBPOOL=2 PAG=1EC14000 NFQ=1EC14008 #FQ=00000005 FRE=0000EF68 POOL CONTROL BLOCK. SUBPOOL=3 PAG=1ECD4000 NFQ=1ECD4008 #FQ=00000002 FRE=00009DF8 PAG=1ED54000 NFQ=1ED54008 #FQ=00000002 FRE=00001750 PAG=1EC84000 NFQ=1EC84008 #FQ=00000001 FRE=00000878 PAG=1ED04000 NFQ=1ED04008 #FQ=00000001 FRE=00000878 PAG=1ED94000 NFQ=1ED94008 #FQ=00000002 FRE=00002768 PAG=1ECF4000 NFQ=1ECF4008 #FQ=00000001 FRE=00000878 AG=1EE04000 NFQ=1EE04008 #FQ=00000001 FRE=00000878 PAG=1ED74000 NFQ=1ED74008 #FQ=00000001 FRE=00000878 PAG=1ECE4000 NFQ=1ECE4008 #FQ=00000001 FRE=00000878 PAG=1EC64000 NFQ=1EC64008 #FQ=00000001 FRE=00000878 POOL CONTROL BLOCK. SUBPOOL=4 PAG=1EC04000 NFQ=1EC04008 #FQ=00000004 FRE=0000CFA0 POOL CONTROL BLOCK. SUBPOOL=5 PAG=1ECA4000 NFQ=1ECA4008 #FQ=00000002 FRE=0000D870 PAG=1ED14000 NFQ=1ED14008 #FQ=00000001 FRE=000043B8 PAG=1ED24000 NFQ=1ED24008 #FQ=00000001 FRE=000043B8 PAG=1EC74000 NFQ=1EC74008 #FQ=00000001 FRE=0000A1D8 PAG=1EC54000 NFQ=1EC54008 #FQ=00000001 FRE=0000A1D8 PAG=1EBB4000 NFQ=1EBB4008 #FQ=00000001 FRE=000043B8 POOL CONTROL BLOCK. SUBPOOL=6 PAG=1EBF4000 NFQ=1EBF4008 #FQ=00000002 FRE=00000A50 PAG=1EBE4000 NFQ=1EBE4008 #FQ=00000001 FRE=00000088 PAG=1EBD4000 NFQ=1EBD4008 #FQ=00000001 FRE=000000B8 PAG=1EBC4000 NFQ=1EBC4008 #FQ=00000001 FRE=000000D0 PAG=1EBA4000 NFQ=1EBA4008 #FQ=00000001 FRE=00000108 POOL CONTROL BLOCK. SUBPOOL=7 PAG=00000000 NFQ=00000000 #FQ=00000000 FRE=00000000 POOL CONTROL BLOCK. SUBPOOL=8 PAG=1ECB4000 NFQ=1ECB4008 #FQ=00000001 FRE=0000FDB0 ALLOC=0001240K, FREE=0000479K, TOTAL=0001728K VIR0272I END The display response is split into a summary section for each subpool and a detailed allocated page block and free queue element display for each subpool. In the summary display, each subpool has two displayed values. The top value is the amount of storage currently allocated and the value below represents the current allocation in 1K chunks and a peak allocation in 1K chunks. For example in the above display in SP5 we can see that there is an allocated value of 317DC bytes, represented by 00C5 in 1K chunks, and a peak value of 04C7 in 1K chunks. At the bottom of the display is a line which provide allocated, free and total values. *Messages* **VIRT0085I** INVALID MEMORY FREE REQUEST. ADDR=aaaaaaaa, SUBPOOL=ss, CALLER=aaaaaaaa' Module : VIR0000 Meaning : The Virtel memory request is invalid because:- - The subpool is invalid. - The address to be freed is outside the associated subpool pages. - The address to be freed is not found in the DSA table. Action : Virtel continues. If you get a significant number of these messages you consider a schedule a restart of Virtel. **VIRT0086E** GETMAIN FAILED. MEMORY DSA DISABLED. Module :VIR0000 Meaning: Virtel was ubale to GETMAIN storage "above the bar" for the DSA table. Action: Increase MEMLIMIT= in the JCL to provide more "above the bar" storage. Virtel continues but you should contact support if the problem continues. Suggest a default of MEMLIMIT=2G. **VIRT0087E** FATAL DSA TABEL ERROR Module :VIR0000 Meaning: The DSA memory table has been corrupted or has been invalidated. Memory diagnostics has been disabled. Action: Virtel continues but you should consider a scheduled restart of Virtel. **VIRT0088E** DSA TABLE FULL. MEMORY DIAGS. DISABLED Module :VIR0000 Meaning: The DSA memory table is full and cannot store further entries. Memory diagnostics disabled. Action: Virtel contines but you should contact support support. Schedule a restart of Virtel. **New TCT Parameters:** New MEMORY parameter - MEMHST MEMORY=(BELOW/ABOVE(DEBUG \| MEMHST \| ALLOW64BITS) MEMORY=(ABOVE,MEMHST) turns on the Virtel memory diagnostic tool. This should only be implemented when advised to do so by Technical Support. Performance degradation might occur due to the additional monitoring services. This will depend on VIRTEL demand. Example:- Use Virtel memory management with memory diagnostic tool and above the bar storage. :: MEMORY=(ABOVE,MEMHST,ALLOW64BITS) **New diagnostic command option - SNAPMSG** The SNAPMSG enhancement allows a SNAP or DUMP to be taken whenever a particular message number is issued by VIRTEL. The command has an additional search field which can be used to identify a message with a particular character string. For example a specific return code. The enhancement is defined within the TCT using the SNAPMSG= keyword or as a command. Command format: :: F VIRTEL,SNAPMSG=msgno[,search],[S|A] TCT keyword: :: SNAPMSG=(msgno,search,action) Default search is none. Default action is SNAP Constraints: - All msgno are 8 characters. - The search field has is restricted to a maximum of 10 Characters. Anything beyond this will be ignored. - Actions: S = SNAP or A = ABEND. - Virtel will abend with a U0999 abend code, reason code 15 if the ABEND action is used. *Messages* **'VIR0262W** SNAPMSG TRIGGERED - VIRTEL ABENDED \| SNAP TAKEN', Module :VIR0002 Meaning A message has been trapped by the SNAPMSG function. Action taken will be either a SNAP dump or an ABEND of VirteL. Action :Determined by TCT parameters or the action set in the SNAPMSG=command. *Examples* TCT: Snap message VIR2102W with search field USSTAB: :: SNAPMSG=(VIR2102W,USSTAB,S), Command: Abend VIRTEL fi message VIR2102W is caught with search field USSX: :: F VIRTEL,SNAPMSG=VIR2102W,USSX,A Response:- 15.35.51 JOB05133 VIR0200I SNAPMSG=VIR2102W,USSX,A 15.35.58 JOB05133 VIRHT51I HTTP-CLI CONNECTING CLVTA078 TO 192.168.092.061:49878 15.35.58 JOB05133 VIR2102W UNABLE TO LOAD THE TRANSACTION USSTAB USSX . DEFAULT USSTAB USSVIRT WILL BE USED. 15.35.58 JOB05133 VIR0055W SNAPMSG TRIGGERED - VIRTEL ABENDED** 15.35.58 JOB05133 VIR0700W ERROR IN TASK MAIN PSW= 078C1000 800E54FE 15.35.58 JOB05133 VIR0400 DATE=14 Dec 2015 TIME= 15:35:58 TASK=MAIN ABEND=ASRA TERM=CLVTA078 APPLICATION=APPLHOLT VERSION=4.55 MVS 15.35.58 JOB05133 VIR0016W ABEND ASRA TERM=CLVTA078 PROG= OFFSET=+0000 15.35.58 JOB05133 VIR0016W PSW = 078C1000 800E54FE 0002000D 00000000 15.35.58 JOB05133 VIR0016W R7 = VIR0010 +39C2 15.35.58 JOB05133 VIR0016W R8 = VIR0021W +1000 15.35.58 JOB05133 VIR0016W R10 = VIR0099 +0000 15.35.58 JOB05133 $HASP375 SPTHOLTV ESTIMATE EXCEEDED BY 78,000 LINES 15.36.02 JOB05133 VIR0038I SNAP COMPLETE 15.36.03 JOB05133 $HASP375 SPTHOLTV ESTIMATE EXCEEDED BY 138,000 LINES 15.36.04 JOB05133 IEA995I SYMPTOM DUMP OUTPUT 953 953 USER COMPLETION CODE=0999 REASON CODE=0000000F 953 TIME=15.35.58 SEQ=04869 CPU=0000 ASID=001C 953 PSW AT TIME OF ERROR 078C1000 800E54FE ILC 2 INTC 0D 953 ACTIVE LOAD MODULE ADDRESS=000E5178 OFFSET=00000386 953 NAME=VIR0002A 953 DATA AT PSW 000E54F8 - 00181610 0A0D9240 A7A7D208 953 GR 0: C4000000 1: C40003E7 953 2: 220B987C 3: 1EBF8278 953 4: 00035A4B 5: 00035A79 953 6: 00000000 7: 1EA8972A 953 8: 1EC6DDF0 9: 1EC0B778 953 A: 00036100 B: 1EBC4668 953 C: 000E5178 D: 0011CCE8 953 E: 0000002E F: 0000000F 953 END OF SYMPTOM DUMP **Virtel Logger extract and format program.** VIR0002B is a program that can be run to extract the VIRTEL records from the System Logger. The VIRTEL log is written to the system logger when LOG=LOGGER is specified in the TCT. *Program Details* SAMPLE JCL: :: //* //* DESCRIPTION //* //LOGGER PROC P= //S01 EXEC PGM=VIR0002B,PARM='&P' //STEPLIB DD DSN=VIRTEL.LOADLIB,DISP=SHR //VIRLOG DD SYSOUT=*,DCB=(LRECL=255,BLKSIZE=25500,RECFM=VB) // PEND //S01 EXEC LOGGER,P='DELETE(>2)' *Parameters* :: (>nnn) COPY [-------------------] (fromdate[,todate]) (>nnn) DELETE [-------------------] (date) Date format = yyyyddd Examples: COPY Copy all records COPY(>2) Copy records older than 2 days COPY(>0) Copy up to yesterday DELETE(>2) Delete records older than 2 days COPY(2015047) Copy records from 2015.047 COPY(2015047,2015048) Copy records from 2015.047 thru to 2015.048 DELETE(2015047) Delete records prior to 2015.047 COPY(>0),DELETE(>1) Will copy records from the previous and earlier, and will then delete from 2 days ago leaving about 24 hours of data in the log stream. *Messages* **VIR0280I** Parameter Error Module : VIR0002B Meaning :Invalid parameters in PARM field. Action :Correct PARM field and provide valid parameters. **VIR0281E** System Logger Error. xxxxxxxx. Return Code xx, Reason code nnnn Module : VIR0002B Meaning :Logger service has failed in routine *xxxxxxxx* Action :Contact technical support. **VIR0282W** No records in range specified Module : VIR0002B Meaning :The parameters provided in the PARM field did not select any records from the log. Action :Check that valid parameters have been provided. **VIR0283W** The log stream is empty Module : VIR0002B Meaning :The log stream has no Virtel records. Action :None. **VIR0284W** Records are not available. xxxxxxxx. Return code xx, Reason code xxxx Module : VIR0002B Meaning :Logger service failed to extract any records due to an error in routine xxxxxxxx. Action :Correct technical support. **VIR0285E** Unable to open DDNAME VIRLOG Module : VIR0002B Meaning :The VIRLOG output DDNAME failed to open. Action :Correct the JCL and rerun the job. **New JCL Parameters. IP= and CLONE=** The purpose of this feature is to lower the coupling between the TCT, ARBO and instances of VIRTEL so that there is less dependency on the parameters defined in the ARBO and TCT for any one VIRTEL instance. This feature enables JCL parameters to override parameters found in the TCT and ARBO. *IP=nnn.nnn.nnn.nnn keyword* Currently the IP address used by VIRTEL for a particular line can be derived from being:- - Explicitly defined in the LINE definition in the ARBO statements - Defaults to the IP stack HOME address. The TCP/IP GETHOSTID function is used to obtain this address. This change implements the possibility to override option (b) with the ability to specify the IP address as a keyword in the JCL PARM field. As an example:- :: //S01 EXEC PGM=VIR0000,PARM="01,MYAPPL,,192.168.0.123" This reduces the need to specify the HOME address in the ARBO for inbound lines thereby reducing the coupling between the various VIRTEL instances that could be running within a complex and the ARBO structures. Inbound address can just define the port via the :port structure only rather than the full nnn.nnn.nnn.nnn:port specification. The IP= keyword will provide the nnn.nnn.nnn.nnn address structure for a particular instance of Virtel. So one ARBO file could provide common port addresses and the VIRTEL instance complements this with a specific IP address using the JCL IP= parameter. This also allows VIRTEL to utilize a multi TCP/IP stack environment without the need for duplicated ARBO files. *CLONE=NN keyword* Currently, VIRTEL makes use of the System Symbolic &SYSCLONE to enable substitution of the "+" character with the two character symbolic value of the System Symbolic. This can be used the TCT APPLID field and terminal relay names defined in the ARBO. The purpose is to facilitate the common use of an ARBO file across multiple instances of VIRTEL, however, this feature is restricted to supporting only one instance of VIRTEL per LPAR. When multiple instances are required on any one LPAR the System Symbolic &SYSCLONE and SYSPLUS=YES feature do not provide sufficient uniqueness, consequently multiple ARBO files are required. This feature endeavours to remove the restriction by providing an override through the use of the CLONE=nn keyword in the JCL parameter. When specified, the CLONE value will override the IBM system symbolic value and will be used to replace the "plus" character as defined in the APPLID or terminal relay names. JCL example: :: //S01 EXEC PGM=VIR0000,PARM='EH,,,192.168.170.30,00' This will start Virtel with the TCT called VIRTCTEH, use a default home address of 192.168.170.30 and override and "+" character with the value "00". The APPLID=APPLEH+ keyword, as defined in the TCT, will become APPLID=APPLEH00 The CLONE= value replaces the IBM symbolic value, consequently the SYSCLONE-SYMBOL within scenario statements will now represent the JCL CLONE= value in scenario statements such as: :: VALUE-OF (SYSCLONE-SYMBOL) or :: COPY$ SYSTEM-TO-VARIABLE,VAR='VAR1', * FIELD=(VALUE-OF,SYSCLONE-SYMBOL) The CLONE= value will also override any &SYSCLONE symbolic that may be specified in dataset names within the TCT. For example:- :: STATDSN=(SP000.SPVIREH.SYS&&SYSCLONE..STATA, STATS=MULTI * SP000.SPVIREH.SYS&&SYSCLONE..STATB), STATS=MULTI * The STATDSN keyword as defined in the TCT will allocate and use datasets:- :: SP000.SPVIREH.SYS00.STATA and SP00.SPVIREH.SYS00.STATB. *Messages* **VIR0098E** INVALID JCL PARM. JOB TERMINATING. Module :VIR0000 Meaning :The JCL PARM field is incorrect. Virtel cannot continue. Action : Correct the VIRTEL JCL PARM field. **VIR0089W** HOST IPADDR. OVERRIDDEN FROM PARM WITH IP=nnn.nnn.nnn.nnn Module :VIR0000 Meaning :The ARBO didn't specify an IP address for this line. GETHOSTID would have been used but this been overidden by the IP=address specified in the JCL PARM. Action : Virtel will use the IP address in the JCL PARM rather than default to the IP address returned by GETHOSTID. **D VIRTEL,LINES command response updated** **VIR0202I** ALLOCATED IP ADDRESS =nnn.nnn.nnn.nnn Module :VIR0002 Meaning :An additional message has been added to the F VIRTEL,LINES command to indicate the IP address for lines that default to GETHOSTID will be overridden with the IP= address specified in the JCL PARM of the Virtel started task. Action : Virtel will use the IP address in the JCL PARM rather than default to the IP address returned by GETHOSTID. **Trace buffer enhancement and offload.** This enhancement provides additional trace and diagnostic material covering a longer time span. The current VIT trace buffer is 200K which is insufficient to capture time related problems. 200K holds a couple of second’s worth of trace data at the most. This change implements logic which moves the trace buffer to external storage and chains the buffers together. When a trace buffer fills it is automatically moved to external storage above the 2GB storage bar. When taking a snap all trace buffers are printed, first those above the bar and finally the current trace buffer. The external or historical trace facility is controlled by the TCT TRACEON= parameter or the VIRTEL TRACE command. The Virtel Internal Tracing (VIT) has several categories which control the amount of trace data. The categories are:- - No tracing - Minimal tracing. No data elements - Tracing with data elements - Tracing with data elements and external archive The active tracing category is displayed in the TRACE display message:- :: F VIRTEL,TRACE,DISPLAY or F SPVIREH,TRACE,D VIR0200I TRACE,D VIR0208I VIRTEL INTERNAL TRACE = YYY. EXT. BUFFERS = 0001/00FF. VIR0213I NO ACTIVE TRACES Message VIR0208I indicates the VIT status through a three character Y | N display and also provides information about the current number of external buffers used and the maximum available. The three VIT display indicators are as follows:- :: - Y|N No tracing or minimal tracing - Y|N Data elements traced - Y|N External Archive active In the above example, YYY indicates full tracing (Data Elements) with trace archive active. The default setting is YYN which is the equivalent of TRACE=ON. By default external archive tracing is not turned on. TCT option:- :: TRACEON=ON | OFF | (Y | N,Y | N,Y | N) Default = ON Equivalent VIT = YYN Tracing ON OFF Equivalent VIT = NNN Tracing OFF TRACEON=(n,n,n) n = Y| N Set Tracing options Examples:- TRACEON=(N,N,N) Tracing OFF TRACEON=(Y,N,N) Minimal tracing, no data elements TRACEON=(Y,Y,N) Default Full tracing, no archive . TRACEON=(Y,Y,Y) Full tracing with archive Command Option: The VIT tracing categories can be set through the F VIRTEL,TRACE command:- :: F VIRTEL,TRACE,VIT=nnn nnn correspond to the three Y|N indicators. Example: :: F VIRTEL,TRACE,VIT=YYY Turn on full VIT tracing plus external buffer archive. *Ability to offload trace buffers to a dataset* With the external VIT trace facility comes the ability to offload the trace buffers to a dataset. This offload capability can be triggered when the maximum number of external trace buffers have been reached, as identified in message VIR0208I, or through an operator command: :: F VIRTEL,TRACE,VIT=OFFLOAD. *Setting up for trace "OFFLOAD"* The trace buffers are offloaded to a GDG dataset which means historical trace data can be kept. To set up the GDG see the below. This job can also be found in the SAMPLIB dataset as member DEFTRGDG:- :: //* //* DEFINE THE TRACE GDG DATASET //* //DELETE EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* DELETE VIRTEL.TRACE.GDG GDG DELETE VIRTEL.TRACE.GDG.DSCB NVSAM SET MAXCC=0 //ALLOC1 EXEC PGM=IEFBR14 //FILE DD DSN=VIRTEL.TRACE.GDG.DSCB, // UNIT=3390,DISP=(NEW,CATLG), // SPACE=(TRK,(0,0)),VOL=SER=VVVVVV, // DCB=BLKSIZE=13300 //* //ALLOC2 EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEF GDG(NAME(VIRTEL.TRACE.GDG) LIMIT(5) SCRATCH NOEMPTY) /* TCT option:- The following TCT options have been added to support the OFFLOAD facility. They are described below. Define the GDG dataset name to be used for the OFFLOAD datasets. The default is VIRTEL.TRACE.GDG:- :: TRCXDSN=gdgdsn Define the number of external trace buffers and action to be taken when that number is reached. Maximum is 999, minimum=1. Default = 255. Action is either CLEAR (Default) or OFFLOAD:- :: TRCXBUF=(nnn[,CLEAR| OFFLOAD]) Example: :: TRCXBUF=(10,OFFLOAD), EXT. TRACE BUFFERS TRCXDSN=SP000.SPVIREH.TRACE.GDG, OFFLOAD DSN TRACEON=(Y,Y,Y), TRACE WITH EXT.HISTORY .. note:: If external buffering is not active any offload command will be rejected as invalid. *Messages* **VIR0208I** VIRTEL INTERNAL TRACE = xxx. EXT. BUFFERS = yyyy/zzzz. Module :VIR0002 Meaning :Provides information about the Virtel Internal Trace status. xxx = VIT status where x is either a Y or N. x.. No tracing or minimal tracing. .x. Full tracing but no archiving ..x Full tracing with external archiving Action : None. **VIR0072E** TRACE TABLE ARCHIVE ERROR. ARCHIVE DISABLED. RC=xx, RE=xx Module :VIR0000 Meaning :Virtel was unable to archive the VIT current buffer. The return and reason codes are displayed. Archive will be disabled. Action : Contact Technical Support. **VIR0073I** TRACE TABLE ARCHIVE OFFLOADED Module :VIR0004 Meaning :The maximum number of external VIT buffers has been reached and a VIT offload has been triggered. Action : None. **VIR0079E** UNABLE TO ALLOCATE OFFLOAD DATASET. R15=RC, R0=RE ,DSN=gdgdsname Module :VIR0004 Meaning :Virtel was unable to allocate the offload GDG. The dynamic allocation return and reason codes are displayed. Action : Check the SVC99 codes to determine why the GDG could not be allocated. Check that the correct GDG base name is being. For additional support contact Technical Support. **USSTAB MSG10 Support** VIRTEL 4.55 now implements the VIR0021W USSTAB menu program. This program will interrogate the customers USSTAB module and create an equivalent 3270 MAP. The MAP will be passed to the VIR0010 routine where it will subsequently be converted into a HTML template and served to the browser. The generated template will provide similar functionality to that of the VTAM USSMSG10, that being a presentation screen and support for USSCMD and USSPARM entries. This allows customers to maintain their USSTAB MSG10 presentation for both VTAM and VIRTEL users without modification. The customers assembled USSTAB module, normally found in USER.VTAMLIB or an equivalent library, must be made available to VIRTEL. This can be done by either copying the module to a VIRTEL steplib library or concatenating the USER.VTAMLIB library into the VIRTEL started procedure. SAMPLIB member USSVIRT can be used to generate the default Virtel USSTAB USSVIRT. .. note:: This is a chargeable feature and you should contact your sales representative for further details.