IBM Shop IBM Support Download
HomeNewsProductsServicesSolutionsAbout IBM
Search 
 

Application Startup File Formats

Application Startup File Formats

9 Nov 1998

 
http://www.ibm.com/nc/pubs

Table of Contents

Introduction

Example Startup File

Startup File Format

  • Application Dependent Items
  • Line Continuation
  • Environment Variables
    •

    Introduction

    This document explains the file format for the application startup files. It is meant to assist you in editing the startup.dft file, which is the only startup file allowed to be hand edited.

    If the startup.dft file exists it replaces all of the other Network Station Manager startup files. Startup.dft is the only startup file processed by the Network Station. If you had made changes using the Startup, Internet->Network, Language, or Select User's Group set up tasks of Network Station Manager, these changes will not take effect on the Network Station.

    When startup.dft exists, the startup files shipped by IBM will not take effect on the Network Station. These shipped startup files contain mandatory environment variable settings. Therefore, in order for the Network Station to work, you must add the following statements to your startup.dft file: 

    SET NSM_NAV_PREF_VERSION R3M0 
SET NSM_NS3270_PREF_VERSION R3M0 
SET NSM_NS5250_PREF_VERSION R3M0 
SET NSM_MWM_PREF_VERSION R3M0 
SET NSM_NCDWM_PREF_VERSION R3M0
    You should delete startup.dft when it is no longer needed.

    All startup files, including startup.dft, are processed by Network Station Login. They are processed by the code that logs you into the Network Station. If you disable the Login code, no startup files will be processed by the Network Station.

    For Release 3, all startup files except startup.dft are stored in UCS-2 format (Unicode). startup.dft can be created in invariant ASCII or UCS-2. You would create the file in UCS-2 if you wish to include non-invariant characters, such as Chinese. However, please note that UCS-2 files must contain big-endian characters. The first two bytes must contain a byte order marker (BOM) of FEFF which indicates that the file is big-endian. 

    Example Startup File

    The following is an example startup.dft file: 
    ! Network Station Manager Release 3.  06/18/98
! Example startup.dft file
!
! NOTE:  This file is meant to provide examples.  It is not
! meant to be used as-is.
!
! When startup.dft exists it becomes the only
! startup file read by the Network Station.  That is,
! the shipped, system-wide, group, and user startup files
! are not read by the Network Station.  For this reason
! you might want to have some statements from the
! other startup files in startup.dft.  Here are some 
! statements that you might want in startup.dft
!
! The following statements came from the shipped startup file.
! START SHIPPED STATEMENTS
VERSION R3M0
SET TRACE ON
SET NSM_HTTP_PORT 80
!
! Env vars to show the 4 buttons on the menu bar
SET NSM_LOGOUT YES
SET NSM_HIDE YES
SET NSM_TOPBOTTOM YES
SET NSM_LOCK YES
!
! These R3M0 statements MUST be in startup.dft
SET NSM_NAV_PREF_VERSION R3M0
SET NSM_NS3270_PREF_VERSION R3M0
SET NSM_NS5250_PREF_VERSION R3M0
SET NSM_MWM_PREF_VERSION R3M0
SET NSM_NCDWM_PREF_VERSION R3M0
!
! Java Just-in-time compiler
SET JITC_ENABLED NO
!
! Run the X Windows Manager (motif)
SET RUNWM YES
!
! The 3 standard application buttons on the menu bar
MENUITEM "5250" ns5250
MENUITEM "3270" ns3270
MENUITEM "NC Navigator" loadb navio
! END SHIPPED STATEMENTS
!
! An alternative to the above would be to just source
! the shipped startup file.  This will pick up all
! the statements above by using a source statement.
SOURCE ${NSM_PROD_SYSDEFAULTS}/startup.nsm
!
! If you had made changes using Network Station
! Manager to system-wide, group, or user startup
! files (startup.nsm or envvars.nsm) these changes
! will not be read by the Network Station.  The
! existence of startup.dft prevents that.  Those
! changes will have to be made here in startup.dft.
! We recommend viewing (BUT NOT SAVING) the
! startup.nsm or envvars.nsm file that you changed
! with Network Station Manager.  Add statements
! to this file to match the statements in startup.nsm
! or envvars.nsm.  NOTE:  startup.nsm and envvars.nsm
! will be in Unicode (double byte chars).  Unless
! you have a Unicode editor the best way to view
! the files would be with a hex editor.

    Startup File Format

    The Startup files contain statements in the following format: 
    ACTION parameters \r\n
    Each action may be terminated with a carriage return and line feed (represented by "\r\n" in the format examples) or just a line feed. The exceptions are lines with line continuation characters (which are discussed later). The ACTION is one of the following (always in upper case) and is interpreted by the login program:
    • SET - this action will set environment variables. The syntax is "SET parameter value \r\n" An example is "SET MYENVVARNAME MYENVVARVALUE \r\n".
    • RUN - this action will automatically start a program when the user logs onto the IBM Network Station. The syntax is "RUN program_name any_parms_1 parm_2 ... parm_n \r\n".
    • MENUITEM - this action will add a menu item to the menu bar on the IBM Network Station when the user logs on. The syntax is "MENUITEM "label" program_name any_parms_1 parm_2 ... parm_n \r\n" The menuitem will have a text string (label) associated with it and it will be placed as the menu choice. It could have embedded blanks in it, so it must always be in double quotes.
    • SOURCE - the syntax is "SOURCE file-to-be-sourced \r\n" where the file-to-be-sourced would be located and executed by Login upon encountering this action. The file-to-be-sourced must be another startup file and must follow the formats documented herein. An example of a SOURCE action would be: "SOURCE ${NSM_PROD_SYSDEFAULTS}/startup.nsm" -- this would cause the shipped startup.nsm file to be read and the actions executed.
    • ! (comment indicator) - a line beginning with an exclamation point (!) is a comment. Login will ignore these lines.

    Application Dependent Items

    For RUN and MENUITEM actions, the program name and parameters are different for each supported application (5250, 3270, remote programs, VT320, Navio NC Navigator browser, Java Applications and Java Applets). The program_name is used to identify the application, and the parameters are application-dependent. The parameters are sometimes positional and sometimes identified by a switch on the command line. Certain parameters may be required, while others may be optional, and it is all application-dependent. 

    Line Continuation

    The case of RUN and MENUITEM actions for the java applications (java virtual machines), NSM requires the action to span multiple lines in the startup file. In this particular case, a line continuation character (backslash '\') is used. The action is determined to be finished when a carriage return/line feed (\r\n) is encountered without a line continuation character. The java command and options are included on the first line and the first line always has a continuation character and a carriage return / line feed, the java application (class) is on the second line. The second line will have a continuation character if there are arguments to the java application (class), and these would then be on a third line.

    Here is an example of a RUN action for a java application with two lines: 

    RUN java -classpath /java/classes.zip:${BOOTPATH}/java/classes.zip -verify -oss2m \ \r\n 
catsdemo \r\n
    Here is an example of a RUN action for a java application with three lines: 
    RUN java -classpath /java/classes.zip:${BOOTPATH}/java/classes.zip -verbosegc -ss59k \ \r\n 
beandemo \ \r\n 
arg1 arg2 arg3 \r\n

    Environment Variables

    It is sometimes useful to use the value of an environment variable in an application parameter, rather than always typing in a potentially long string. For example, in setting the class path for a bunch of java applications, if the classpath is the same for all, they can simply create an environment variable and have Login substitute the value. The following format is used for environment variable value substitutions: 
    ${ENVVARNAME}
    For example, lets suppose the user has created an environment variable called "MYPATH" and it is set as follows: "SET MYPATH /java/classes.zip \r\n". They could then use ${MYPATH} in place of the classpath value in the example above, as follows: 
    RUN java -classpath ${MYPATH}:${BOOTPATH}/java/classes.zip -verify -oss2m \ \r\n 
catsdemo \r\n
    Note also in this example, the ${BOOTPATH} is substituted with the value of the BOOTPATH environment variable. The difference between BOOTPATH and MYPATH is that the value of BOOTPATH can not be changed by the user.

    Since environment variables may be used in RUN and MENUITEM actions, it is necessary that the SET actions are always built into the startup file before the RUN and MENUITEM actions.

    RESTRICTION: Since environment variables are SET in the startup files in random order (usually), the use of environment variable substitution within the value of another environment variable is not supported. It can't be guaranteed that the value of the environment-variable-to-be-substituted will be known at the time it needs to be substituted. Therefore, environment variable substitutions are only supported in RUN and MENUITEM commands. 

    PrivacyTerms of useContact---