NOMAD Version 6.52 Installation Steps Required with NOMAD 6.52

Support for Teradata Version 2 Release 2

The NOMAD for Teradata Interface supports Teradata Version 2 Release 2 in DBC/SQL mode.

  • Starting with NOMAD Version 6.50, the NOMAD for Teradata Interface only supports versions of Teradata that support DBC/SQL.

On MVS, the person installing this IUT should move the SCTQL420 schema for SCHEMGEN/TQLGEN to the appropriate prefix and translate the schema. For more information, refer to the NOMAD Interim Update Tape Getting Started MVS, IUT 9704.

On VM, the SCTQL420 database is installed on the NOMAD shared disk (N2SHARE). For more information, refer to the NOMAD Interim Update Tape Getting Started VM, IUT 9704.

  • If your site is not running Teradata Version 2 Release 2, you must edit SGENPROF NOMAD and change the value of &SQ_TQL_VER to a valid value, as shown on line 20 of DB2ASGN2 NOMAD.

Updated Databases

The following databases have been updated and should be moved to the appropriate disk on VM or prefix on MVS.

Database Description Operating System
Y2KTRACE Year 2000 tracing output - mapping VM, MVS
TOOLMSGD Tools messages in Dutch VM, MVS
TOOLMSGF Tools messages in French VM, MVS
TOOLMSGI Tools messages in Italian VM, MVS
TOOLMSGS Tools messages in Spanish VM, MVS
OLHELPG Online Help in German VM, MVS
SITMAP internal to NOMAD VM, MVS
SCTQL420
SXDB2510
SCHEMGEN/TQLGEN database for Teradata Version 2 Release 2
SCHEMGEN/DB2GEN database for DB2 Release 5.10 via DRDA on VM
VM
VM
SCDB2510 SCHEMGEN/DB2GEN database for DB2 Release 5.10 MVS
UERRJ NOMAD error messages in Japanese MVS
WRDBFRE QLIST messages in French VM, MVS
WRDBJAP QLIST messages in Japanese MVS
Table of Contents 3


NOMAD Version 6.52 NOMAD Enhancements

Updated Schemas

The following schemas have been updated and should be moved to the appropriate disk on VM or data set on MVS.

Updated Databases

The following databases have been updated and should be moved to the appropriate disk on VM or prefix on MVS.

Schema Purpose Operating System
Y2KTRACE Year 2000 tracing output - mapping VM, MVS
SITMAP Internal to NOMAD VM, MVS
SCTQL420
SCHEMGEN/TQLGEN database for Teradata Version 2 Release 2
VM
SCDB2510 SCHEMGEN/DB2GEN database for DB2 Release 5.10 MVS
SXDB2510 SCHEMGEN/DB2GEN database for DB2 Release 5.10 via DRDA on VM VM

NOMAD Enhancements


TRACE Y2K Command

The TRACE Y2K command identifies areas of NOMAD code that may have Year 2000 compliance problems. When TRACE Y2K is active and questionable conversions are executed during procedural processing, a trace record is written.

TRACE Y2K ON / OFF

Required Parameters

One of the following parameters:

ON Activates the Year 2000 trace feature
OFF Terminates the Year 2000 trace feature.

Table of Contents 4


NOMAD Version 6.52 NOMAD Enhancements

Usage

While NOMAD is largely Year 2000 compliant, it is possible to write NOMAD applications that are not. The TRACE Y2K command notes procedural commands that convert dates using a 2-digit year format (YY format). TRACE Y2K can be used to trace production applications. The commands to activate the trace can be put in a NOMAD profile procedure.

TRACE Y2K can be used with any NOMAD Interface (SQL/DS, DB2, TQL, IMS, IDMS, GEDI), but the trace does not do any interface-specific checking of date manipulation. TRACE Y2K is valid for all non-English-language versions of NOMAD.

  • No translation of error messages associated with this feature will be available until NOMAD Version 7.00.

TRACE Y2K tracks date conversion events for executed commands. In order to ensure complete code analysis, procedures should be tested with all possible code paths. If this is not practical, use alternate scanning tools in conjunction with TRACE Y2K. Because TRACE Y2K tracks commands during their execution, directive statements will not be included in trace results. For example, DATABASE, DBADD, and DEFINE statements, which may contain non-compliant date expressions, will not appear in the trace. However, a statement that evaluates a DEFINE that references a non-compliant date expression during procedural execution will appear in the trace results. TRACE Y2K checks any date manipulation executed within NOMAD; it cannot check date manipulation operations external to NOMAD (e.g., in sort, EXEC, or CLIST operations).

  • TRACE Y2K writes trace records only for procedural commands. Interactive commands are not traced.

TRACE Y2K can be helpful in analyzing the @SYSTEM profile, the database profile, and other profile procedures under a shared database server, but TRACE Y2K will not record activity relating to database access requests from users running as database drivers. Remember, TRACE Y2K tracks procedural commands and, so, has limited value if used to track shared database processing.


Y2K Trace Results File

The TRACE Y2K command works in conjunction with the TRACE FILE command. Issue the TRACE FILE command to indicate the trace file file-id where TRACE Y2K records should be written. The name of the trace file is flexible and can conform to the site's file naming conventions. Trace records are written in external format and can be viewed with any file browse facility. The disk space required for the results file depends on the number of lines of date-dependent code in the target application.

For more information on the TRACE FILE command, refer to the Chapter 10 in the NOMAD Reference Manual.

If TRACE FILE is not issued, Y2K trace output is sent to the default output device (SYSPRINT). For interactive NOMAD, this is the terminal display. For batch NOMAD, this is the job log. For production applications, it may be more convenient to direct output to a printer rather than allocating a new disk file. Trace output can be directed to a printer with the command TRACE FILE PTR.

Since TRACE FILE is used for general tracking, Y2K trace records can be interspersed with other types of traces, e.g., TRACE ON (procedure), SQL, DB2, or GEDI.

  • If Y2K trace records are mixed with other types of trace output, the Y2KTRACE SCHEMA (described below) cannot be easily used to analyze Y2K trace contents.
Table of Contents 5


NOMAD Version 6.52 NOMAD Enhancements

In order to minimize trace output, once a trace record is written for a given statement, no additional trace records are written for it. Further trace events that occur involving that statement are ignored, regardless of whether a different trace event occurs. Once a statement is traced, a NOMAD application programmer should examine the statement and make any corrections needed for Year 2000 compliance. There is an exception to 6 NOMAD Version 6.52 NOMAD Enhancements the single trace record rule. If a PURGE command is issued to remove the procedure (and its statements) from memory, and the procedure is re-executed, the statement may be flagged again and a record written to the trace file again.

The following example shows how to direct TRACE Y2K records to a file named Y2K TRACE:

trace y2k on;
trace file y2k;
!
!
activate TRACE Y2K
open Y2K TRACE file
!
!
...      
call n2appl; ! run application !
...      
trace close;
trace y2k off;
!
!
close Y2K TRACE file
turn off TRACE Y2K
!
!


Closing the trace file when quitting from NOMAD is not required. Trace files are automatically closed at NOMAD termination.

On VM, a trace file should not be defined on a disk on which database writes are being done. If a RESTORE occurs either explicitly by command or implicitly due to a procedure error, the trace records may be lost. Refer to Chapter 14 in the NOMAD Reference Manual for information on SAVE and RESTORE.

Once a statement is traced, a NOMAD application programmer should examine the statement and make any corrections needed for Year 2000 compliance. Even after corrections have been made to a command or a procedure, it may be advisable to keep TRACE Y2K ON. There may be additional problems areas in the procedure, particularly procedures that contain long, non-procedural commands such as LIST. For example, a single LIST command may require corrections for several item references. Subsequent traces may point out areas that were missed by the initial correction attempts, or some of the attempted corrections may not be Year 2000 compliant.

Trace Record Format

TRACE Y2K records are formatted as follows:
Y2K: pppppppp sssss.ss ccccccc eeee
where the trace record fields are:
  Y2K:record identifier
ppppppppprocedure name
sssss.ssstatement number
cccccccNOMAD command
eeeetrace event code
Sample Y2K trace file output:
Y2K:
Y2K:
Y2K:
Y2KTEST
Y2KTEST
Y2KTEST
1.01
2.01
3.01
PRINT
ASSIGN
WINDOW
0001
0002
0003
Table of Contents 6


NOMAD Version 6.52 NOMAD Enhancements

Trace Record Characteristics

NOMAD commands are processed by specialized internal NOMAD routines. The command name that appears in a TRACE Y2K record is taken from the name of its internal NOMAD processing routine. This causes some command names to appear in the trace differently than they are specified in the NOMAD procedure syntax. For example:

  • &X = &DATE appears as ASSIGN in the trace output.
  • CRLIST appears as LIST in the trace output.

If an INCLUDE command is used to process additional NOMAD code within a procedure, the included lines appear as if they are part of that main procedure. The TRACE Y2K records will show the file name of the main procedure, not the file name of the procedure executing via the INCLUDE. Because the INCLUDE lines are treated as part of the main procedure, line numbers of subsequent lines in the main procedure are incremented by the number of included lines. Therefore, you must allow for INCLUDE lines when you are interpreting the output from TRACE Y2K. The commented lines at the beginning of each statement in the following example show the statement number assigned during execution of the procedure.

PROCA NOMAD:

 
!1.01! INCLUDE PROCB;
!4.01! &D = &DATE;
!5.01! &DT = &DATETIME;
!6.01! PRINT &D;
!7.01! PRINT &DT;


PROCB NOMAD:

 
!2.01! DECLARE &D AS DATE;
!3.01! DECLARE &DT AS DATETIME;


The NOMAD2 command LIST and TYPE parameters both provide a way to get a line-numbered version of a procedure. The output from LIST or TYPE reflects any code triggered by an INCLUDE command. For example:

N2 PROCA LIST (LIST

produces the file PROCA LISTING containing the following output:

  FILE--PROCA
    1.01
2.01
3.01
4.01
5.01
6.01
7.01

INCLUDE PROCB;
DECLARE &D AS DATE;
DECLARE &DT AS DATETIME;
&D = &DATE;
&DT = &DATETIME;
PRINT &D;
PRINT &DT;
Table of Contents 7


NOMAD Version 6.52 NOMAD Enhancements

Y2KTRACE SCHEMA

The following schema can be used to browse the contents of the Y2K trace file. The Y2KTRACE SCHEMA and SIT2 are installed with NOMAD Version 6.52.

MASTER Y2KTRACE TYPE QSAM DDNAME Y2KTRACE;  
  ITEM DUMMY
ITEM Y2K_HDR
ITEM DUMMY
ITEM Y2K_PROC
ITEM DUMMY
ITEM Y2K_STMT
ITEM DUMMY
ITEM Y2K_COMMAND
ITEM DUMMY
ITEM Y2K_EVENT_NUM
  AS A1;
AS A4 HEADING ' ' ;
AS A1;
AS A8 HEADING 'Procedure';
AS A1;
AS 99999.99 SETFORM N8.2 HEADING 'Statement';
AS A1;
AS A7 HEADING 'NOMAD:Command';

AS A1;
AS 9999 SETFORM N4 HEADING 'Trace:Event:Code';
! Y2K: !
DEFINE Y2K_EVENT_DESCAS A30 = Y2K_EVENT_NUM DECODE
( 0001 = 'Internal date -> YY',
0002 = 'Internal date -> Packed YY',
0003 = 'YY -> Internal date',
0004 = 'YY -> Packed YY date',
0100 = 'LIST YY',
0101 = 'LIST BY YY',
ELSE = ' ' );

Trace Events

A trace event denotes a point during execution of a NOMAD command where a possible non-compliant Year 2000 date operation is performed. Trace events are detected during various NOMAD operations. A NOMAD command signals an event by setting an event code (&Y2K_EVENT_CODE). A Y2K trace record is written when a trace event occurs during execution of a NOMAD command. The event code is included in the trace record contents to facilitate identification of the date operation being performed. The following Year 2000 trace events are tracked:

Year 2000 Event Code Year 2000 Conversion Event Example of NOMAD Code That Triggers Event Expected Trace Output
0001 Internal date moved to a YY character or numeric value (integer, packed, etc.) ITEM DT AS DATE;
. . .
DEFINE YR1 AS A2 =
DISPLAY(DT AS DATE'YY');
DEFINE YR2 AS A6 =
DISPLAY(DT AS DATE'(0101)YY';
PRINT YR1 YR2;
High
0002 Internal date moved to a packed YY year MASTER Y2EXTERN TYPE QSAM;
ITEM PDT AS DATE
EXTFORM DATE'PMMDDYY';
. . .
&PDT = '04/20/98';
Low
0003 YY character or numeric (integer, packed, etc.) moved to an internal date DEC &C AS A8;
DEC &D AS DATE'MM/DD/YYYY';
&C = '04/20/98';
&D = VALUE(&C SETFORM
DATE'MM/DD/YY');
High
0004 Packed YY year moved to an internal date MASTER Y2EXTERN TYPE QSAM;
ITEM PDT AS DATE "MM/DD/YYYY"
EXTFORM DATE'PMMDDYY';
. . .
FIRST PDT;
PRINT PDT;
Low
0100 LIST or CREATE uses a YY item that is derived from a date. TEM DT AS DATE;
DEFINE YR AS A2 =
DISPLAY(DT AS DATE'YYMMDD');
LIST YR . . .;
High
0101 LIST or CREATE uses a YY sort item that is derived from a date. ITEM DT AS DATE;
DEFINE YR AS A2 =
DISPLAY(DT AS DATE'YYMMDD');
LIST BY YR . . .;
Medium
Table of Contents 8


NOMAD Version 6.52 NOMAD Enhancements

Expected Trace Output reflects the anticipated number of trace records from statements of these types:
  High - indicates a common NOMAD process. An example would be conversion from internal date to
2-character year (YY), which is common in reports and on screen forms.
  Medium - indicates a NOMAD operation that is expected to occur in moderation. An example would be sorting by a non-date item that is derived from a date expression.
  Low - indicates a NOMAD operation that is expected to occur infrequently. An example would be use of packed date external file items.
Tracing of specific Year 2000 events can be controlled with the following &variables:
&Variable Chg/Set Internal Format Initial Value Contains...
&Y2K_EVENT_CODE Chg I2 0 A code representing a trace event recorded by the TRACE Y2K ON command. A Y2K trace event occurs from the execution of a NOMAD command involving a date operation. The value of this &variable is set, and its value recorded in the Y2K trace file, when a date handling command has finished executing. The &variable is reset when a new trace event occurs or when the user assigns a value to it.
&Y2K_OMIT_CODE(0) Chg I2 N/A A list of Y2K event codes to be skipped (that is, not recorded in the Y2K trace file) during execution of the TRACE Y2K ON command.
&Y2K_OMIT_PROC(0) Chg A8 N/A A list of procedures to be skipped (that is, not recorded in the Y2K trace file) during execution of the TRACE Y2K ON command.


Examples

Procedure code for many of the following examples is shown with line numbers for ease in correlating Y2K trace output to the executed code. As mentioned earlier, the TYPE parameter or the LIST parameter of the NOMAD2 command can be used when invoking NOMAD to produce a line-numbered version of a procedure:

N2 procname (TYPE

Table of Contents 9


NOMAD Version 6.52 NOMAD Enhancements

When a procedure is run with the TYPE parameter, a line-numbered display of the procedure is typed on the terminal (or SYSPRINT device). When a procedure is run with the LIST parameter, a file named procname LISTING is generated with line numbers annotating each statement.

Example 1: Activating TRACE Y2K in the NOMAD Profile

The following example shows how to automatically activate TRACE Y2K when invoking NOMAD through a command placed in the NOMAD profile procedure. This method could be used to trace production applications where it is more convenient to direct the output to a printer rather than allocating a new disk file:

PROFILE NOMAD:

trace y2k on;
trace file ptr;
! activate TRACE Y2K !
! direct trace output to printer !
if query('whencalled') = 'EXIT' then
  do;    
    call exitproc;  
      return;
    end;  
option exitprocedure on;  

EXITPROC NOMAD:

trace close;
trace y2k off;
! close trace file !
! turn off TRACE Y2K !


Example 2: Activating TRACE Y2K in a Procedure

The following procedure, TRACEY2K NOMAD, turns on TRACE Y2K, runs a procedure, and turns off the trace in order to collect the trace output for the procedure:

TRACEY2K NOMAD:

!1.01! trace y2k on;
!2.01! trace file y2k;
!3.01!  
!4.01! call myproc;
!5.01!  
!6.01! trace y2k off;
!7.01! trace close;

The procedure MYPROC NOMAD creates future dates extending into the year 2000 using the ADDATE function. The procedure then produces a report sorted by a two-digit year in character format:

MYPROC NOMAD:

!1.01!
!2.01!
!3.01!
!4.01!
da newcmpny;
define future_purch as date = addate(purchdate,0,16);
define futureyy as a2 = display(future_purch as date'yy');
list by deptname across futureyy sum(curval);
Table of Contents 10


NOMAD Version 6.52 NOMAD Enhancements

MYPROC NOMAD produces the following report sorted across the two-character alphanumeric values of FUTUREYY. Notice that the ACROSS sort order, visible in the initial heading line of the report, is out of order by date. The sort is being done on the item named FUTUREYY, which represents the last two digits of the year values, but in the format of an alphanumeric character expression. The introduction of the value 00 for the first time invalidates the report sort order. The character value 00 is placed at the start of the sort order rather than at the end where the date value 2000 should appear.

PAGE 1        
DEPARTMENT
----------
00
SUM
CURRENT
VALUE
----------
96
SUM
CURRENT
VALUE
----------
98
SUM
CURRENT
VALUE
----------
99
SUM
CURRENT
VALUE
-----------
ACCOUNTING
MAINTENANCE
PERSONNEL
SALES
5,641.14

94.79
182.62
-392.89


78.90
252.64
22.74

163.14

28.56
319.09

File Y2K TRACE is produced when the trace file is closed. It includes only the single line:

Y2K: MYPROC 4.01 LIST 0100

The trace Year 2000 event code 0100 indicates that a character item derived from a DATE'YY' format conversion is being used in a LIST command and that the LIST may need to be changed for Year 2000 compliance.

A possible correction for this type of problem is to define a date expression that lets NOMAD's date conversion routines display within the sort heading in AS DATE'YY' format while sorting internally on the complete date value. Some extra work is needed in the DEFINE expression to combine all dates that fall within a given year into a single month and day value for each year.

MYPROC2 NOMAD:

!1.01! da newcmpny;
!2.01! define future_purch as date = addate(purchdate,0,16);
!3.01! define futureyy as date'yyyy' =
!4.01!   '01/01/' cat display(future_purch as date'yyyy');
!5.01! list by deptname across futureyy as date'yy' sum(curval);

Note the difference in the ACROSS sort order:

PAGE 1        
DEPARTMENT
----------
00
SUM
CURRENT
VALUE
----------
96
SUM
CURRENT
VALUE
----------
98
SUM
CURRENT
VALUE
----------
99
SUM
CURRENT
VALUE
----------
ACCOUNTING
MAINTENANCE
PERSONNEL
SALES
-392.89


78.90
252.64
22.74

163.14

28.56
319.09
5,641.14

94.79
182.62

File Y2K TRACE is still produced. When the trace file is closed, it includes only a single line:

Y2K: MYPROC 5.01 LIST 0001

Table of Contents 11


NOMAD Version 6.52 NOMAD Enhancements

Notice that the AS DATE'YY' display format in the LIST command is flagged. Although this only converts an internal date to an external display format with two digits (AS DATE'YY'), the item is not being converted to a non-date data type. Thus, any sorting or other operation on the item done by LIST would use NOMAD internal date manipulation. A display of a date value in YY format is not considered to be critical to the outcome of the resulting report. Nevertheless, a low trace event value is signaled in order to warn that you might want to change the procedure because of the two-digit year display.

Example 3: Preventing Certain Trace Events

This example shows how to prevent certain trace events from being recorded in the Y2K TRACE file. In this case, trace event 0001, which tracks conversions of any internal date to two-character year format, will not be recorded in the Y2K TRACE file. This event can occur frequently during execution of a NOMAD application and can cause a sizable trace file to be generated. As conversion of date items to two-character year format is not necessarily a Year 2000 compliance problem for reporting output, display of data on screens, or the like, you may want to restrict this event from the trace.

First, procedure YYREPORT NOMAD is run without restricting trace events:

CALLYYR1 NOMAD:

!1.01!
!2.01!
!3.01!
!4.01!
!5.01!
!6.01!
!7.01!
trace y2k on;
trace file y2k;

call yyreport;

trace y2k off;
trace close;

Following is the report procedure.

YYREPORT NOMAD:

!1.01!
!2.01!
da newcmpny;
list by deptname curval purchdate as date'yy';

This is the report produced:

PAGE 1    
DEPARTMENT
----------
CURRENT
VALUE

---------
PURCHASE
DATE
---------
ACCOUNTING 50.69
112.23
89.66
-356.64
5,640.07
-36.46
82
82
82
80
84
80

MAINTENANCE

. . .

   
Table of Contents 12


NOMAD Version 6.52 NOMAD Enhancements

The following Y2K TRACE file is produced. The two-digit date display is flagged in the LIST. Although this is a conversion of an internal date to external YY format, the item is not being converted to a non-date data type. Thus, any sorting or other operation on the item done by LIST would use NOMAD internal date manipulation. A display of a date value in YY format is not considered to be critical to the outcome of the resulting report. Nevertheless, a low trace event value is signaled in order to signal that you might want to change the procedure if this is of concern in this particular situation.

Y2K: YYREPORT 2.01 LIST 0001

Since date-to-YY conversion is quite common, it may be desirable to restrict this from trace results. The following example shows how to prevent occurrences of trace event 0001 from being recorded in the Y2K TRACE file.

CALLYYR2 NOMAD:

!1.01!
!2.01!
!3.01!
!4.01!
!5.01!
!6.01!
!7.01!
!8.01!
trace y2k on;
trace file y2k;
&y2k_omit_code = 1;

call yyreport;

trace y2k off;
trace close;

Example 4: PURGE Command

Use of PURGE to delete compiled procedures from memory during a NOMAD session, and subsequent re-execution of the procedure, can cause duplicate entries in the Y2K TRACE file.

CALLDEPT NOMAD:

!1.01!
!2.01!
!3.01!
!4.01!
!5.01!
!6.01!
!7.01!
!8.01!
!9.01!
trace y2k on;
trace file y2k;
call deptrpt ACC;
purge deptrpt;
call deptrpt PER;
purge deptrpt;
call deptrpt SAL;
trace y2k off;
trace close;
DEPTRPT NOMAD:
!1.01!
!2.01!
!3.01!
!4.01!
!5.01!
!6.01!
!7.01!
!8.01!
da newcmpny;
proc (?dept);
trans;
select deptnum = '?dept';
untrans;
print 'Report generated on: ' (&datetime);
list by idname across index vdays;
select clear;

The following Y2K TRACE file shows the effect of PURGE. Note the repeat of records for statements 6.01 and 7.01 that use YY date conversions. Purging and rerunning (recompiling) the procedure causes any prior indication of Y2K tracking for those statements to be lost.

Table of Contents 13


NOMAD Version 6.52 NOMAD Enhancements

 

Y2K:
Y2K:
Y2K:
Y2K:
Y2K:
Y2K:

DEPTRPT
DEPTRPT

DEPTRPT

DEPTRPT

DEPTRPT

DEPTRPT

6.01 PRINT
7.01 LIST

6.01 PRINT

7.01 LIST

6.01 PRINT

7.01 LIST
0001
0001
0001
0001
0001
0001

A report from theY2K TRACE file can sort by procedure name and statement number to eliminate duplicates, reducing the amount of data to analyze.

Y2KRPT NOMAD:

file define y2ktrace y2k trace;
da y2ktrace;
list by y2k_proc

 

by y2k_stmt  
 
first(y2k_command)
heading 'Command'
    first(y2k_event_num) heading 'Event:Code'
    first(y2k_event_des) heading 'Description'
  headasis;  
file clear y2ktrace;

Following is the report produced from the trace file:

PAGE 1        
Procedure
---------
Statement
---------
Command
-------
Event
Code
-----
Description
--------------------------
DEPTRPT 6.01
7.01
PRINT
LIST
1
1
Internal date -> YY
Internal date -> YY

Example 5: DEFINE Statement

DEFINE statements that contain problematic date handling are not traced directly by TRACE Y2K; that is, the definition of a DEFINE expression is not traced. But conversion operations involving those DEFINE expressions are traced. The following example uses several DEFINE date expressions that convert a date item to various date formats:

Table of Contents 14


NOMAD Version 6.52 NOMAD Enhancements

Y2KDEFN NOMAD:

! 1.01! trace y2k on;  
! 2.01! trace file y2k;  
! 3.01!    
! 4.01! da newcmpny;  
! 5.01! define dtdflt as date =  
! 6.01!   purchdate; ! default date (YY)!
! 7.01! define dtyy as date'yy' =  
! 8.01!   purchdate; ! date YY !
! 9.01! define cdtyy as a2 =  
!10.01!   display(purchdate as date'yy'); ! Character YY !
!11.01! define ndtyy as 99 =
!12.01!   value(display(purchdate as date'yy')); ! Numeric YY !
!13.01!    
!14.01! list purchdate limit 2; ! no trace !
!15.01! list dtdflt limit 2;   ! trace !
!16.01! list dtyy limit 2;   ! trace !
!17.01! list cdtyy limit 2;   ! trace !
!18.01! list ndtyy limit 2;   ! trace !
!19.01!          
!20.01! trace close;      
!21.01! trace y2k off;      


Following is the Y2K TRACE file generated during execution of the procedure.

  Y2K: Y2KDEFN
Y2K: Y2KDEFN
Y2K: Y2KDEFN
Y2K: Y2KDEFN
15.01 LIST
16.01 LIST
17.01 LIST
18.01 LIST
0001
0001
0100
0100

Notice that the DEFINE statements do not appear in the trace. The LIST commands that reference the DEFINED items do appear in the trace, since conversion of date data to a YY format occurs during access and display of the date data. The first LIST, which uses the database item PURCHDATE:

  FROM DEPARTMENT
SEGMENT EQUIPMENT
ITEM PURCHDATE AS DATE'MON, YYYY' HEADING='PURCHASE:DATE';

does not appear in the trace, because its use of a YYYY date format will not result in truncation of century information.

While TRACE Y2K flags the command performing data conversion as the statement with a problem, the correction will likely be a change to the DEFINE statement, not necessarily to the command that was flagged by TRACE Y2K.


NOMAD2 Command - DATE, QUIET and SVC11 Parameters

There are four formats for the NOMAD2 command:

  • The NOMAD2 command is issued from the operating system environment either to execute a procedure or to enter the NOMAD interactive environment. When used to execute a procedure, NOMAD returns control to the operating system when the procedure completes execution.
  • The NOMAD2 command with the DBCHK parameter causes a DBCHK to be performed on the specified database(s).
  • The NOMAD2 command is issued with the SHARE parameter to specify that the session runs in shared mode.
  • On VM, the NOMAD2 command is issued with the VERSION parameter to specify that an alternate version of NOMAD is to be invoked.
Table of Contents 15


NOMAD Version 6.52 NOMAD Enhancements

For VM:

NOMAD2 / NOM2 / N2 [procedure-name] [procedure-parameter] ...
[([TYPE] [LIST] [EXTEND] [NOPROF] [SCANSIZE nn]
[SVC11] [QUIET] ) ]

NOMAD2 / NOM2 / N2 ([DBCHK]) [(DATE) date] database-name ...

NOMAD2 / NOM2 / N2 (SHARE [NOPROF] [EXTEND] [QUIET] [SVC11][)]

NOMAD2 / NOM2 / N2 ({VERSION [x] [EXECUTE] [OVERLAY] [QUIET] [SVC11] } / [PURGE] )
For MVS:
NOMAD2 [procedure-name] [procedure-parameters] ...
[(MVSPREVIX mvsprefix)]
[([TYPE] [LIST] [EXTEND] [NOPROF]
[SCANSIZE nn ] [SVC11] [)] ]

NOMAD2 ([DBCHK]) [(DATE) date] database-name ...

NOMAD2 (SHARE database-name [NOPROF] [EXTEND] [SVC11][)]
[(MVSPREFIX mvsprefix [)] ]

Required Parameters

[no changes]


Optional Parameters

(DATE) date (Documentation Clarification)

Restricts the DBCHK to those segments in the database(s) that have been modified since the specified date. The date may be entered in any acceptable DATE format, but is restricted to eight characters on VM. This parameter is subject to OPTION DATEORDER when OPTION DATEORDER is specified in the user's PROFILE, @SYSTEM PROFILE or NSM RGNPROC profile.

EXECUTE (VM only) (Documentation Clarification)

Invokes NOMAD. When the NOMAD session is terminated, the loaded version of NOMAD is purged.

If the VERSION parameter is not specified when using EXECUTE, the version defaults to the that which is defined as the NOMAD2 shared segment.

Table of Contents 16


NOMAD Version 6.52 NOMAD Enhancements

SVC11

Specifies that NOMAD be invoked using TIME SVC rather than store clock (STCK) instructions to determine the current date. This allows Year 2000 testing of NOMAD applications through third-party software products that reset the date by intercepting calls to OS TIME SVC (SVC 11).

QUIET (VM only)

Specifies that normal messages be suppressed during the VM NOMAD initiation.

Usage

NOMAD2...DBCHK - DATE Specification (Documentation Clarification)

DBCHK is issued from the operating system command level. Use NOMAD2...DBCHK and the name(s) of the database(s) to be checked. Optionally, the DATE parameter can be used. When databases are checked on a periodic basis, this parameter can be used to eliminate unnecessary checking by specifying the date of the previous DBCHK. An example of the command with DATE is:

NOMAD2 (DBCHK) (DATE) 11/15/98 LANIF LANIFINT

Any date format that does not require a discrete AS DATE format specification (for example, formats MM/DD/YY, MMDDYYYY, and MMDDYY) are all acceptable. The date portion is limited to eight characters on VM. If OPTION DATEORDER has been issued in a user or a system profile procedure, this date will obey the OPTION DATEORDER specification.

QUIET Parameter (VM Only)

When it is necessary to suppress normal messages during NOMAD initialization on VM, specify the QUIET parameter. This causes messages such as NOMAD2 LOADED to be suppressed. Error messages are still displayed.

SVC11 Parameter

The SVC11 invocation parameter allows single applications to be easily tested by allowing users to invoke the normally installed version of NOMAD yet have NOMAD use the TIME SVC. When NOMAD is invoked using the SVC11 parameter, NOMAD uses the TIME SVC to get the date when setting &DATE and &DATETIME. This makes Year 2000 testing with third-party software, which resets the date by intercepting calls to OS TIME SVC (SVC 11), possible.

Recommendation: When performing Year 2000 testing, change the SCV11 setting for all NOMAD users via the SVC11 option of $NOMOPTS. Refer to the earlier section "Year 2000 Testing: $NOMOPTS - SVC11 Option."

  • If the application being tested uses the NOMAD shared database facility, both the driver and the server should use the same SVC11 settings (either both with SVC11 set to YES or both with SVC11 set to NO). If this is not done, invalid results may occur when SELECTs, INSTANCEs, and/or LIST...WHEREs are shipped using &DATE or &DATETIME. Similarly, if interfaces to other products are in use, when an adjusted date selection criteria is passed to the target product, errors may result if the target product cannot handle a Year 2000 date.

Examples

Example 1: DBCHK Parameter - DATE Specification

if your PROFILE NOMAD has:

option dateorder dm ;

Table of Contents 17


NOMAD Version 6.52 NOMAD Enhancements

When you issue:

n2 (dbchk) (date) 25/05/98 lanif

NOMAD checks that the date of the last DBCHK was earlier than May 25, 1998, before executing the DBCHK.

Example 2: QUIET Parameter (VM Only)

The example on the left shows YNOMAD2 being loaded and then entered, and the response from the system to each command. The example on the right shows YNOMAD2 being loaded and then entered using the QUIET parameter. Notice that the message (YNOMAD2 ) is suppressed.

n2 (ver y YNOMAD2 LOADED Ready: T=0.04/0.06 11:37:23 n2 (quiet) NOMAD2 Dev Ver 900D 21May98

n2 (ver y
YNOMAD2 LOADED
Ready: T=0.04/0.06 11:36:51
n2
(YNOMAD2 )
NOMAD2 Dev Ver 900D 21May98
n2 (ver y
YNOMAD2 LOADED
Ready: T=0.04/0.06 11:37:23
n2 (quiet)
NOMAD2 Dev Ver 900D 21May98


Example 3: SVC11 Parameter

To invoke NOMAD with OS TIME SVC to determine values for &DATE or &DATETIME issue:

nomad2 (svc11)

  • The SVC11 invocation parameter may be used with a version of NOMAD that has been installed with SVC11 set to YES in $NOMOPTS with no resulting problems, but use of both methods simultaneously is unnecessary.

SVC11 can be specified with other invocation parameters in any order, except it should not come between another parameter and its argument(s).

NOMAD2 procname procparm (SVC11 QUIET)

For more information on Year 2000 testing, refer to the earlier section "Year 2000 Testing: $NOMOPTS - SVC11 Option."


CREATE FOR LOTUS123 Command

CREATE FOR LOTUS123 is used to format data from NOMAD-accessible databases into files that can be imported into a PC worksheet package, such as Lotus 1-2-3. CREATE FOR LOTUS123 produces a file with detail data, a text file containing 1-2-3 format instructions, and a worksheet file in Lotus 1-2-3 internal format containing a load macro that automates the loading and formatting of the data. These files are sent to the PC through the file transfer facilities available at your site. Once the files are available on the PC, the information can be loaded into a PC worksheet package.

With the introduction of Lotus 1-2-3 For Windows, the macro processing and worksheet compatibility underwent significant changes. These enhancements of CREATE FOR LOTUS123 are designed to accommodate these processing changes.

Table of Contents 18


NOMAD Version 6.52 NOMAD Enhancements

File Names

File type and file-id are used to construct a file name. File-id is either TEMP or the name in the ON parameter specified by the CREATE FOR command. The following types of files can be generated:

File Type Description
PRN A data file containing detail data and heading information that can be imported into a PC worksheet. This file is generated for both CREATE FOR LOTUS123 and CREATE FOR WORKSHEET.
TXT A text file, containing 1-2-3 formatting instructions invoked by a load macro. The format instructions load data from the data file and define column (item) formatting information.
WKS A worksheet file in 1-2-3 internal format. The file is used to automate loading of data and formatting of information. The worksheet file contains a load macro designed to be used with the format file and the data file.

Worksheet File (WKS File)

In addition to the data file and the text file, CREATE FOR LOTUS123 generates a worksheet file. Although the TXT and PRN files can be transferred to the PC with text formats, the WKS file should be transferred to the PC with a binary format.

The created worksheet is empty except for a macro used to start column formatting and data loading. By default, the worksheet file is created with the file type WKS. This file is generally then downloaded to the PC with the file extension .WKS. Not all versions of Lotus 1-2-3 allow smooth operation with the load macro when the worksheet file is assigned the PC file extension WKS. For some versions of Lotus 1-2-3, the file extension WK1 is required for the load macro contained within the worksheet file to function smoothly. For this reason, a new system &variable &WKSEXTN has been implemented. &WKSEXTN controls the file type of the worksheet file produced by CREATE FOR LOTUS123. When the file is downloaded, the file type is generally transformed into the PC file extension. If your version of Lotus 1-2-3 requires that the worksheet file be downloaded to the PC with the extension WK1, change the NOMAD &variable &WKSEXTN from its default value of WKS to WK1. The value recommended for all users of Windows versions of Lotus 1-2-3 is WK1. The value for &WKSEXTN can be set in an individual user's profile if users at a site have various levels of Lotus 1-2-3.

A prompt string telling the user to run the load macro may be displayed if the user has changed the macro name from "\0" to some other name. A macro named "\0" is automatically executed when a worksheet is retrieved; a macro with another name must be explicitly executed by the user when the worksheet opens. For example, if &WKSMACRO='\A', when the worksheet is retrieved in the 1-2-3 environment, the worksheet will display a message:

 

Table of Contents 19


NOMAD Version 6.52 NOMAD Enhancements

Use the menu choice to run the macro (Tools>Macro>Run) or use the keystroke shortcut. When a single letter has been designated as the macro name, as "\A" in this example, depending on the version of Lotus 1-2-3, a keystroke shortcut is automatically available. In Lotus 1-2-3 Release 2 and 3 for DOS, press the ALT key plus the specified letter; in Release 4 or higher, press the CTRL key plus the letter specified to execute the macro. The slash visible in the message is the internal convention for identifying macros in Lotus 1-2-3, not a keystroke value to be pressed.

By default, this prompt message is not displayed, because a macro with the name "\0" is executed automatically when the created worksheet is retrieved. The worksheet file automates data loading into Lotus 1-2-3. The WKS file is designed to be used with Lotus 1-2-3 since:

  • it contains format information that applies only to 1-2-3, and
    • it contains no data, so it cannot be used by another package

In many cases, if the worksheet package has sufficient compatibility with Lotus 1-2-3, the worksheet file and the macro function much as they do with Lotus 1-2-3. If the worksheet file will not open or the macro will not function, the PRN data file can still be imported into the other worksheet package by using an ASCII text import facility.

DATE and DATETIME Display Formats

DATE and DATETIME data are generated in integer format representing the number of days relative to December 31, 1599. The TIME component of DATETIME data is ignored. In Lotus 1-2-3, a date outside the worksheet range is displayed as an overflow (***).

Lotus 1-2-3 requires that a date column be formatted with additional character width when displaying years greater than 1999. Any year value of 2000 or greater will display with a four-digit year value automatically. If the column for the date value has not been assigned the extra needed character width, the display shows as an overflow (***). Although initially the display seems to signal an error, if the column width is adjusted, the data appears. To ensure that Year 2000 dates display correctly in a downloaded spreadsheet, a new system &variable &WKSYEARDIGITS has been implemented. &WKSYEARDIGITS can be assigned a value of 2 or 4. A value of 2 is sufficient if only dates less than the year 2000 are displayed. If date values that contain the year 2000 or greater will be part of the data, &WKSYEARDIGITS should be set to 4. A setting of 4 ensures that sufficient formatting space is allocated to the date columns so that an overflow display is avoided.

The NOMAD display formats and their Lotus 1-2-3 equivalents are unchanged, but the Lotus 1-2-3 formats D1, D3, and D4, which contain year values in their display, are automatically displayed enlarged from a two-digit year (YY) to a four-digit year (YYYY) when the year values are greater than 1999.

New System & Variables

The following system &variables can be used to specify global formatting information.

&Variable Chg/Set Internal Format Default Value Contains...
&WKSEXTN Chg A3 WKS the file extension of the generated worksheet file. WK1 is the recommended value for Windows versions of Lotus 1-2-3.
&WKSYEARDIGITS Chg I2 2 Allocates additional space required by four-digit year values for D1,D3, and D4 Lotus 1-2-3 date formats. Four-digit year values are automatically generated by Lotus 1-2-3 when year values are greater than 1999. Specify 4 when year values of 2000 and higher will be included in the downloaded data. (LOTUS123 only)
Table of Contents 20


NOMAD Version 6.52 NOMAD Enhancements

Transferring NOMAD-Generated Files to a Worksheet Product

This section contains examples of how to transfer the three files generated by CREATE FOR LOTUS123 into Lotus 1-2-3. If another worksheet product is the target and it is sufficiently compatible with Lotus 1-2-3, the same steps can be followed to automatically open and load the worksheet file. If the product is not sufficiently compatible with Lotus 1-2-3, the PRN data information can be imported using an ASCII text import facility.

Transferring Files to Lotus 1-2-3

To transfer data from NOMAD on VM to Lotus 1-2-3 on your PC, follow these steps:

1. Within NOMAD, type the following command:
  create jobcode jobname
    across index hisal
    for lotus123
    on sample1 ;
  The following three files are generated:
  sample1 prn
  sample2 wks
  sample3 txt
2.

Use an available file transfer package to transfer the files to the PC.

Use a file extension for the worksheet file that is appropriate for the version of 1-2-3 being used. The default file extension can be changed during the transfer, or the file type generated on the mainframe can be set to the appropriate value by using the system &variable &WKSEXTN. Both the data file (PRN) and the text file (TXT) that contains the format information must be transferred with the default extensions specified below:

NOMAD File Type PC File Extension Description Lotus 1-2-3 Release
WKS .WKS
.WK1
Worksheet
Worksheet
1.0
2.0 or later
PRN .PRN Date File all
TXT .TXT Format File all
The worksheet (WKS) file must be transferred as binary while the other files should be transferred with EBCDIC/ASCII character conversions.
Table of Contents   21


NOMAD Version 6.52 NOMAD Enhancements

3. From the DOS environment, from the Lotus 1-2-3 directory, execute 1-2-3:
  cd 123
123s
  From Windows 3. x, click on the Lotus 1-2-3 icon in the Program Manager. for lotus123
  From Windows 95 , click on the Start Menu item or the shortcut that executes Lotus 1-2-3.
4. Within 1-2-3, load the created worksheet with either /File Retrieve if you are using 1-2-3, or /File Open from Windows. For example:
  /File Retrieve sample1.wk1
5. If the default macro name "/0" has been used, the data is automatically loaded into the worksheet and formatted. If another macro name has been used, a prompt appears, asking which macro to run.
6. The data is now ready to be used in Lotus 1-2-3.


Shared Database - OPTION CENTURYBREAK and OPTION DATEORDER

Behavior Change in NOMAD Version 6.52

The results returned for queries against a shared database may change in NOMAD Version 6.52 when OPTION CENTURYBREAK or OPTION DATEORDER is used. Information on the client's OPTION CENTURYBREAK and OPTION DATEORDER settings is now sent to the server. The evaluation of the user's requests will be influenced by the server's consideration of the values of these settings. For example, if a SELECT or WHERE clause contains a date literal compared to the value of a date item, the literal date value will be evaluated according to the client's setting for OPTION CENTURYBREAK and OPTION DATEORDER. In versions of NOMAD earlier than 6.52, the server's settings for OPTION CENTURYBREAK and OPTION DATEORDER determined the evaluation of the literal.

  • A shared database's server and client must both be running the same version of NOMAD. If the client and the server are not both running the same version, an incompatible versions error is returned when the DATABASE or DBADD command is issued.


Shared Database - Passing Database Profile

In Version 6.52, the maximum length of a database profile record is no longer restricted to 8K.

A shared database profile and all of its called procedures are sent to the driver in a minimum of 8K blocks. However, the block size is increased when a record larger than 8K is encountered.


CLEAR SYSTEM Command With OPTION CENTURYBREAK

Behavior Change in NOMAD Version 6.52

The CLEAR SYSTEM command does not clear the setting of the OPTION CENTURYBREAK command.

Table of Contents 22

copyright The Boeing Company, 1997, 1998, 1999, 2000, 2001
No part may be printed, reproduced or distributed without prior written permission
Used here with permission of The Boeing Company Line Management, Customer Relations, Ethics, Legal and Copyright Offices
All images on this site ©1996-2001, Judy Tallant, All Rights Reserved, except where noted.
Permission must be obtained for use of any image
contained herein for any purpose.