SysWorks©

SysWorks
Command Reference Manual
Previous Contents Index

By default the current context is assumed.

See the UTLTOOLS FETCH SUBCONTEXT command for more details about the keywords and their values.

/CREATED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /CREATED selects files based on their dates of creation. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/CONSOLIDATION=consolidation-filespec

/NOCONSOLIDATION (default)

Specifies whether a single consolidated target file should be created. If specified, this consolidated file will consist of the final contents of each target file checked and/or created. If /IF_NEWER is specified and a target file is already uptodate, it is copied into the consolidation file. If a new target file is generated, it is also written to the consolidation file. This feature is mainly used to create a complete MMS script from the set of source based MMS scripts generated during the BUILD command RULES phase.

By default, /NOCONSOLIDATION is assumed.

/DEFAULT=([SOURCE=src-file-type],[TARGET=trg-file-type])

/NODEFAULT (default)

Specifies the default file type for source and/or target files.

By default, /NODEFAULT is assumed.

/DOCUMENTATION_FILE_TYPES

Specifies which source file types cause the target within a generated MMS script to be in the documentation directory rather than the software directory.

By default, /DOCUMENTATION_FILE_TYPES=(.DECW$BOOKSHELF_SRC.INX_LIST.RND.RNH.RNM.RNR. SDML) is assumed.

/DUPLICATES (default)

/NODUPLICATES

When negated specifies that where multiple versions of a specific source file name and type exist, only the first one found will be converted. This is useful when the source file specification contains a search list or wildcarded directory. Specifying this (/NODUPLICATES) with wildcard versions results in only the latest versions being converted.

By default, /NODUPLICATES is assumed which is the required action for MMS script generation.

/EXCLUDE=(file-spec[,...])

Excludes the specified files from the conversion operation. You can include a directory but not a device in the file specification. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /EXPIRED selects files according to their expiration dates. (The expiration date is set with the SET SECURITY/EXPIRED command.) The /EXPIRED qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/IF_NEWER

/NOIF_NEWER (default)

Specifies whether a conversion should be performed in the target file already exists and its revision date and time is later than that of the source files.

By default, /NOIF_NEWER is assumed.

/IF_POSSIBLE (default)

/NOIF_POSSIBLE

Specifies whether to only process source files for which a converter could be found.

By default, /IF_POSSIBLE is assumed.

/LOG[=(option[,...])]

/NOLOG

Specifies which file action messages are displayed (if any) by CONVERT/GENERATE command.

The following log options are available:
ALL Indicates that all file action messages should be displayed.
NONE Indicates that no file action messages should be displayed. This is the same as /NOLOG.
CHECKED Indicates that a message should be displayed for each source file checked for conversion.
GENERATED Indicates that a message should be displayed for each target file generated.
UNNECESSARY Indicates that a message should be displayed for each target file not generated because it was already uptodate. See /IF_NEWER for a more detailed description of an uptodate target.

/MODIFIED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /MODIFIED selects files according to the dates on which they were last modified. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /EXPIRED. If you specify none of these four time modifiers, the default is /CREATED.

/SELECT=(keyword[,...])

Allows you to select files based on a number of criteria. Choose one of the following keywords:
ACL
NOACL 		Selects files that have an associated ACL or files that do not (NOACL keyword).
ATTRIBUTES=(option[,...]) Selects files which have particular attributes. The following options are supported:
Option Description
[NO]BACKUP Selects files which have backups enabled (BACKUP) or disabled (NOBACKUP)
LRL=MAXIMUM=size Selects files which have a longest record size less than or equal to the specified value.
LRL=MINIMUM=size Selects files which have a longest record size greater than or equal to the specified value.
ORG=type Selects files which have the specified organization. Valid organizations include:
  • DIRECT
  • INDEXED
  • RELATIVE
  • SEQUENTIAL
RFM=type Selects files which have the specified record format. Valid record formats include:
  • STREAM
  • STREAMCR
  • STREAMLF
  • UNDEFINED
  • VARIABLE
  • VFC
FILE=(option[,...]) Selects portions of the file specification for display purposes. The /SELECT=FILE qualifier is used to turn off specific portions by explicit or implicit specification of the options. Possible options are:
  • [NO]NODE
  • [NO]DEVICE
  • [NO]DIRECTORY
  • [NO]NAME
  • [NO]TYPE
  • [NO]VERSION

/SELECT=FILE qualifier cannot be used with the /FULL qualifier.

ONLINE
NOONLINE 		Selects files that are online or shelved.
PRESHELVED
NOPRESHELVED 		Selects files that are preshelved or not preshelved.
SHELVABLE
NOSHELVABLE 		Selects files that are shelvable or not shelvable.
SIZE=(option[,...]) Selects files according to their size. Possible options are:
Option Description
MAXIMUM=n Selects files that have fewer blocks than the value of n, which defaults to 1,073,741,823. Use with MINIMUM=n to specify a size range for files to be selected.
MINIMUM=n Selects files that have blocks equal to or greater than the value of n. Use with MAXIMUM=n to specify a size range for files to be selected.
(MINIMUM=n, MAXIMUM=n) Selects files whose block size falls within the specified MINIMUM and MAXIMUM range.

/SINCE=[time]

Selects only those files dated after the specified time. You can specify time as an absolute time, a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

See the OpenVMS DCL Concepts Manual for complete information on specifying time values.

/SUBCONTEXT=(keyword=value,...)

Specifies the various directories and libraries which will be used during MMS script generation.

See the DEVTOOLS BEGIN SUBCONTEXT command for more details about the keywords and their values.

/REDUCE

/NOREDUCE (default)

Specifies whether a consolidated MMS target file should have intermediate dependencies removed where possible. The intermediate target file contents which are removed include:

The reduction uses a soft recursive algorithim that also removes circular dependencies. Targets of the above file types are only removed if they are used in a source list. Conversly, sources are only removed if a corresponding target can be found. Leaving targets and sources which don't have correpsonding opposites allows dependencies defined in or used by other MMS scripts to be used or defined.

By default /NOREDUCE is assumed.

/STYLE[=code]

Specifies which style generated sources should follow. This is mainly used by MMS script generators to specify whether to use MMS style or make style.

The following tyle codes are available:
OPENVMS Indicates that MMS style scripts should be generated. These use depends_on for dependencies and long MMS$ xxxx macros for substitution.
UNIX Indicates that make style scripts should be generated. These use the colon character for dependencies and short macros for substitution.
VMS Same as specifying OPENVMS.
WINDOWSNT At the current time, this is the same as specifying UNIX.

/SUFFIX

/NOSUFFIX (default)

Specifies whether the source file type is appended to the source file name in order to deterine the target file name. If specified, the resultant name is truncated to 39 characters. This feature is mainly used to resolve ambiguities where two sources share the same file name and both need generated targets with the same file type.

For example, MY_PROG.COB and MY_PROG.OPT would both result in generated MMS scripts of MY_PROG.MMS unless the /SUFFIX qualifier was specified. The result when /SUFFIX is specified would be MY_PROG_COB.MMS and MY_PROG_OPT.MMS.

By default, /NOSUFFIX is assumed.

/WORK=directory-code/NOWORK (default)

Specifies that the default work directory used in generating MMS scripts should be changed to another directory.

The following directory codes are available:
LIBRARY Indicates that the library directory should be used in place of the work directory. Typically this would be used to generate MMS scripts for sources which have been generated in the library directory.

Examples

#1 

$ CVTMMS :== 'DEVTOOLS' CONVERT/GENERATE/DEFAULT=TARGET=.MMS_INC

Set up a CVTMMS command which can be used to convert any source to an MMS script. An example of using this would be CVTMMS MYPROG.MAR which would generate an MMS script named MYPROG.MMS_INC.

#2 

$ DEVTOOLS CONVERT/GENERATE FIN_WRK_DIR:*.* FIN_LIB_DIR:-
_$/CONSOLIDATION=FIN_LIB_DIR:FIN_APPENDS.MMS-
_$/DEFAULT=TARGET=.MMS_INC/IF_NEWER/IF_POSSIBLE/LOG=GENERATED/SUFFIX

Performs all the MMS script generation required for a BUILD command RULES phase.

#3 

$ REDUCE :== 'DEVTOOLS' CONVERT/GENERATE/DEFAULT=(SOURCE=.LOG,TARGET=.ERR)

Set up a REDUCE command which can be used to reduce a log file containing all types of messages and text to an error file containing only errors. See the REDUCE command for more details.

DEVTOOLS CONVERT/GENERATE/SYMBOLS

Converts an object or symbol file into an append or include source file.

This generic command is primarily used to generate sources used during builds.

Format

DEVTOOLS CONVERT/GENERATE/SYMBOLS symbol-file output-file

Parameters

symbol-file

Specifies the name of an existing object or symbol file to be converted. No wildcards are allowed.

output-file

Specifies the name of the output append or include source file which is generated from the object or symbol file. The file type of the output file is used to control which format the output file has. The following file types are supported:
File Type Format and Usage
.COM_APP DCL command procedure append source. A DCL global numeric symbol assignedment is generated for each symbol found in the source file.
.H C/C++ include file. A #define statement is generated for each symbol found in the source file.

If you do not specify the device or directory, the DEVTOOLS CONVERT/GENERATE/SYMBOLS command uses your current default device and directory.

Examples

#1 

$ DEVTOOLS CONVERT/GENERATE/SYMBOLS FIN_LIB_DIR:FIN_MESSAGES.SYM -
_$ FIN_SFT_DIR:FIN_MESSAGES.H

Generates a C include file from the symbol values in the message symbol file. This include file can then be used in C sources to provide values for the applications messages without resorting to the globalvalue clause.

DEVTOOLS COPY

Copies a file or a set of files to a target file. This command is similar to the DCL COPY command with the addition of some extra qualifiers.

Format

DEVTOOLS COPY input-filespec[,...] output-filespec

Parameters

input-filespec[,...]

Specifies the name of an existing file to be copied. The asterisk (*) and the percent sign (%) wildcard characters are allowed. If you do not specify the device or directory, the DEVTOOLS COPY command uses your current default device and directory.

output-filespec

Specifies the name of the output file into which the input is copied.

You must specify at least one field in the output file specification. If you do not specify the device or directory, the DEVTOOLS COPY command uses your current default device and directory. The DEVTOOLS COPY command replaces any other missing fields (file name, file type, version number) with the corresponding field of the input file specification. If you specify more than one input file, the DEVTOOLS COPY command generally uses the fields from the first input file to determine any missing fields in the output file.

You can use the asterisk (*) wildcard character in place of any two of the following: the file name, the file type, or the version number. The DEVTOOLS COPY command uses the corresponding field in the related input file to name the output file.

Qualifiers

/BACKUP

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /BACKUP selects files according to the dates of their most recent backups. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /CREATED, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/BEFORE[=time]

Selects only those files dated prior to the specified time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

See the OpenVMS DCL Concepts Manual for complete information on specifying time values.

/BINARY

/NOBINARY (Default)

Specifies whether binary file types are forced to have standard binary file attributes during the DEVTOOLS copy operation. The standard binary file attributes are the equivalent to those set by the command DEVTOOLS SET FILE/ATTRIBUTES=(RFM=FIX,LRL=512,RAT=NONE).

By default, file attributes are not forced to the standard binary file attributes.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC using standard UIC format as described in the OpenVMS DCL Concepts Manual.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each copy operation to confirm that the operation should be performed on that file. The following responses are valid: 


     YES      NO       QUIT 
     TRUE     FALSE    [Ctrl/Z]
     1        0        ALL 
              [Return]

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CREATED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /CREATED selects files based on their dates of creation. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/EXCLUDE=(file-spec[,...])

Excludes the specified files from the copy operation. You can include a directory but not a device in the file specification. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /EXPIRED selects files according to their expiration dates. (The expiration date is set with the SET SECURITY/EXPIRED command.) The /EXPIRED qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/LOG[=(option[,...]) (default)

/NOLOG

Outputs messages to the output file depending upon the option(s) specified.

The following log options are available:
Option Meaning
[NO]ALL Log all information. This is the default action.
[NO]ERROR Log errors.
[NO]NONE Don't log any information. This is the equivalent to /NOLOG.
[NO]NOTFOUND Log files that were not found.
[NO]SUCCESS Log files that were copied.

/MODIFIED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /MODIFIED selects files according to the dates on which they were last modified. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /EXPIRED. If you specify none of these four time modifiers, the default is /CREATED.

/RECORD

/NORECORD (Default)

Specifies whether file contents should be explicily copied in record mode.

When a file is copied to or from a record oiriented device, the contents are always copied in record mode. When copied from and to a block oriented device, such as a disk, the default behaviour is to copy in block mode. This qualifier can be used to force the contents to be copied in record mode.

For operating systems or file systems which don't have specific support for record mode, the qualifier has no effect.

By default, /NORECORD is assumed.

/RETAIN=(item[,...])

/NORETAIN (Default)

Specifies whether certain file attributes are retained during the DEVTOOLS copy operation.

Valid items include:
Item Usage
CDT Creation date and time
RDT Revision date time

/RLF (Default)

/NORLF

Specifies whether related file specification handling is used during the DEVTOOLS copy operation.

By default, /RLF is assumed.

/SELECT=(keyword[,...])

Allows you to select files based on a number of criteria. Choose one of the following keywords:
ACL
NOACL 		Selects files that have an associated ACL or files that do not (NOACL keyword).
ATTRIBUTES=(option[,...]) Selects files which have particular attributes. The following options are supported:
Option Description
[NO]BACKUP Selects files which have backups enabled (BACKUP) or disabled (NOBACKUP)
LRL=MAXIMUM=size Selects files which have a longest record size less than or equal to the specified value.
LRL=MINIMUM=size Selects files which have a longest record size greater than or equal to the specified value.
ORG=type Selects files which have the specified organization. Valid organizations include:
  • DIRECT
  • INDEXED
  • RELATIVE
  • SEQUENTIAL
RFM=type Selects files which have the specified record format. Valid record formats include:
  • STREAM
  • STREAMCR
  • STREAMLF
  • UNDEFINED
  • VARIABLE
  • VFC
FILE=(option[,...]) Selects portions of the file specification for display purposes. The /SELECT=FILE qualifier is used to turn off specific portions by explicit or implicit specification of the options. Possible options are:
  • [NO]NODE
  • [NO]DEVICE
  • [NO]DIRECTORY
  • [NO]NAME
  • [NO]TYPE
  • [NO]VERSION

/SELECT=FILE qualifier cannot be used with the /FULL qualifier.

ONLINE
NOONLINE 		Selects files that are online or shelved.
PRESHELVED
NOPRESHELVED 		Selects files that are preshelved or not preshelved.
SHELVABLE
NOSHELVABLE 		Selects files that are shelvable or not shelvable.
SIZE=(option[,...]) Selects files according to their size. Possible options are:
Option Description
MAXIMUM=n Selects files that have fewer blocks than the value of n, which defaults to 1,073,741,823. Use with MINIMUM=n to specify a size range for files to be selected.
MINIMUM=n Selects files that have blocks equal to or greater than the value of n. Use with MAXIMUM=n to specify a size range for files to be selected.
(MINIMUM=n, MAXIMUM=n) Selects files whose block size falls within the specified MINIMUM and MAXIMUM range.

/SINCE=[time]

Selects only those files dated after the specified time. You can specify time as an absolute time, a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

Previous Next Contents Index