Creates a new module in the current VDE library.

Requires CREMOD privilege.

Format

CREATE MODULE mod-name [, mod-name...]

Parameter

mod-name

The name of the module being created. The module name must consist of a module name and a module type separated by a period (as in MODNAM.FOR). It may optionally be preceded by a facility name enclosed in square brackets (as in [ACCTNG]MODNAM.FOR where ACCTNG is the facility name). If no facility name is specified, the module is assumed to belong to the current default facility. The facility name, module name, and type name may each be up to 39 characters long and must follow VDE name syntax.

Description

The CREATE MODULE command creates a new module in the current VDE library. It records the new module in the VDE database, including its facility, name, type, remark string, and other attributes. Every module belongs to some facility, either the facility you explicitly specify or the current default facility.

Modules are classified as source modules or derived modules. A source module is a text file (normally) which you create and modify manually with an editor. A source module can be reserved from and replaced into the VDE library with the RESERVE and REPLACE commands. The text of each source module is stored in a delta file within a CMS library in the form of a CMS "element."

By default, the CREATE MODULE command does not create the initial generation of a source module. Instead it records the module in the VDE database and reserves it for you in your default development stream. You must then use the REPLACE command to actually create the initial generation of the module. This should be the normal way of creating new modules once the VDE library is established. However, if you use the /INPUT or /FROM_DIRECTORY qualifier, the CREATE MODULE command creates the initial generations of the new modules; these qualifiers are useful when you initially establish your VDE library. (Note that /INPUT may not be available, depending on the setting of the queued-replacement option on the stream. If /INPUT is not accepted, you must use a subsequent REPLACE command to specify the contents of the module under creation.)

A derived module is a file or other entity that is produced by an automated build step, such as an object module or an executable image. A derived module cannot be reserved or replaced. In most cases, VDE automatically enters derived modules into the VDE database when the modules are produced; you seldom need to enter them with the CREATE MODULE command. However, when a derived module needs to be entered into the database manually, you can do so with the /DERIVED qualifier to the CREATE MODULE command.

If a module is mistakenly created, one can use the DELETE MODULE command to reverse the action and delete it---the UNRESERVE command will refuse to delete modules that lack a first generation.

The DELETE MODULE command allows the creator of an errant module to correct simple mistakes---such as a misnamed module---without requiring unusual privileges. With the DELETE MODULE command, the creator can delete the module prior to the initial module replacement. DELETE MODULE will cancel the outstanding reservation on the module, will remove the module from any reservation session that it might be included in, and will prevent the module from ever appearing in the VDE library. For further information on the DELETE MODULE command, see DELETE MODULE. (The DELETE MODULE command normally requires DELMOD privilege. In this particular situation, CREMOD privilege is sufficient to permit module deletion.)

Qualifiers

/BINARY

/NOBINARY (default)

Specifies whether the source module is a binary file or not. The /BINARY qualifier specifies that the source module is a binary (non-text) file. Binary source files cannot be reviewed or differenced with the REVIEW REPLACEMENT command because they do not consist of ordinary ASCII text. The /NOBINARY qualifier specifies that the source module is an ordinary ASCII text file. These qualifiers are only meaningful for source modules.

Large files that undergo extensive changes at frequent intervals, or are the output of a language or application, may not be suited for storage as standard delta files as the file delta is never used, occupies a considerable amount of disk space, and grows rapidly. See the /MARKER qualifier. Examples of files well-suited for storage as marker files include most executable images, object files, Postscript files, and BACKUP savesets.

/CONCURRENT(default)

/NOCONCURRENT

Specifies whether the module can be reserved concurrently by more than one user. The /CONCURRENT qualifier allows the module to be reserved concurrently unless a user overrides this default with for a specific reservation. The /NOCONCURRENT qualifier specifies that the module cannot be reserved concurrently.

/DELETE

/NODELETE

Controls whether the delete attribute is set for the new facility. This attribute allows the facility to be deleted with the DELETE FACILITY command. The /DELETE qualifier sets the delete attribute so that the new facility can be deleted. The /NODELETE qualifier clears the delete attribute so that the new facility cannot be deleted unless you first reset this attribute with a MODIFY FACILITY command. Marking a facility as /NODELETE makes it harder to accidentally delete the facility.

If this qualifier is not specified, VDE uses the value of the allow-deletion library attribute. The library allow-deletion default attribute can be set or reset by using the /ALLOW_DELETE qualifier on the CREATE LIBRARY or on the MODIFY LIBRARY command.

/DERIVED

/SOURCE (default)

Specifies whether the new module is a source module or a derived module. By definition, a source module is a module that can be reserved from and replaced into the library. The generations of each such module is stored in a "delta file" (a CMS element). Most source modules are text files that you modify with an editor, but VDE also supports binary (non-text) source modules.

A derived module is a module that is produced from source modules or other derived modules by an automated build step. It cannot be reserved or replaced, and is often ignored during command wildcard processing. Derived modules are automatically recorded in the VDE database when they are produced; they are seldom entered into a library with the CREATE MODULE command. However, new source modules are not automatically recorded in the VDE database and must be entered into a library with the CREATE MODULE command. For this reason, the /SOURCE qualifier is the default.

/FROM_DIRECTORY=dir-spec

Specifies that modules be created for all files in a specified disk directory. The dir-spec parameter gives the OpenVMS directory specification of the disk directory. When this qualifier is specified, the mod-name parameters are omitted, and the CREATE MODULE command creates a new module in the current default facility for each file in the specified directory. Each file becomes the initial generation of the corresponding module. The dir-spec parameter may also consist of a wildcarded file specification, in which case VDE creates a module for each file that matches the specification. (This feature can be used to create modules for only those files in a directory that have a certain file extension, for example.) This qualifier lets you enter a large number of new modules into the VDE library with a single command, provided that the initial versions of those modules are stored in a single disk directory and that all modules belong to the same facility.

The initial generation of each module created with this qualifier is inserted into (becomes the latest generation of) the stream you specify with the /STREAM qualifier or into the default stream if you omit the /STREAM qualifier. It is also inserted into all successors of that stream.

This qualifier requires the PERFREP privilege.

/HISTORY[="string"]

/NOHISTORY[="string"] (default)

Specifies the CMS history string to be associated with the module and whether history information should be included in source files when modules are retrieved with the FETCH or RESERVE command. History information gives a historical record of previous changes to the module.

The /HISTORY qualifier specifies that history information should be included in source files by default when such files are retrieved with the FETCH or RESERVE command. The /NOHISTORY qualifier specifies that history information should be omitted. The string parameter to either qualifier specifies the default history string if the user specifies that history information should be included in a retrieved file. (If you specify the /NOHISTORY qualifier on the CREATE MODULE command, you must use the /HISTORY qualifier on the FETCH or RESERVE command to use the default history string.) If you do not specify a string parameter, VDE supplies a default history string that depends on the module type.

See the CMS documentation for a description of the CMS history string and its format.

/INPUT[=file-spec]

The /INPUT qualifier causes the CREATE MODULE command to create the initial generation of the new module. This qualifier is only applicable to source modules. The file-spec parameter gives the OpenVMS file specification of a file that contains the initial generation of the module. If the file-name part of the file specification is omitted, the file name is assumed to be the same as the module name. If the directory specification part is omitted, the file is assumed to be in your current default directory. If you omit the whole file-spec parameter, VDE creates the initial generation from the file in your default directory with the same name as the new module.

The initial generation of each module created with the /INPUT qualifier is inserted into (becomes the latest generation of) the stream you specify with the /STREAM qualifier or into the default stream if you omit the /STREAM qualifier. It is also inserted into all successors of that stream.

If neither /INPUT nor /FROM_DIRECTORY is specified, the CREATE MODULE command records the module in the VDE database and marks it as reserved to you. You must then use the REPLACE command to actually create the initial generation of the module. This is the preferred way of creating new modules once a VDE library has been established.

The /INPUT qualifier is rejected on any streams marked for queued replacement. To create and insert a module on a stream marked for queued replacement, omit the /INPUT qualifier, and specify the file to load into the new module via a REPLACE command.

This qualifier require the PERFREP privilege.

/LOG (default)

/NOLOG

Controls whether log messages are printed after the new modules have been created. The /LOG qualifier prints the messages and /NOLOG suppresses them. The messages indicate that the new modules have been added to the VDE library and that the database transaction has successfully committed.

/MARKER

/NOMARKER (default)

Specifies whether the source module uses a marker file or not. The /MARKER qualifier specifies that the source module uses a marker file. When a source module uses a marker file, the module is stored as an ordinary file in one of the delta-file directories. A small text file, called the marker file, contains the full file name of that source file, and this marker file is stored in the module's delta file (CMS element). In short, the delta file contains a small text file that points to the module's actual source file. The marker-file mechanism is normally only used for large or frequently changed binary source modules, for which the delta-file mechanism may give poor performance or use excessive disk space. Executable images, object modules, Postscript files, and BACKUP savesets are all example of "source" modules for which the marker-file mechanism may be appropriate.

The actual source files for modules that use marker files are stored in a subdirectory for the module's facility within the VDE library's delta-file directory tree. This subdirectory must have the special directory symbol VDE$MARKER. See the description of the SET DIRECTORY command for an explanation of how to establish subdirectories and assign them directory symbols. See the description of the command SHOW DIRECTORY/DELTA for information on displaying the current marker file directory (or directories) setting.

The /NOMARKER qualifier specifies that the source module does not use a marker file and that its text is stored directly in the delta file (CMS element) for the module. Ordinary ASCII text modules should not use marker files.

Also see the /[NO]BINARY qualifier.

/NOTES[="string"]

/NONOTES[="string"] (default)

Specifies the CMS notes string to be associated with the module and whether CMS notes should be included in source files when modules are retrieved with the FETCH or RESERVE command. CMS notes indicate in what module generation each source line was created.

The /NOTES qualifier specifies that notes information should be included in source files by default when such files are retrieved with the FETCH or RESERVE command. The /NONOTES qualifier specifies that notes information should be omitted. The string parameter to either qualifier specifies the default notes string if the user specifies that notes information should be included in a retrieved file. (If you specify the /NONOTES qualifier on the CREATE MODULE command, you must use the /NOTES qualifier on the FETCH or RESERVE command to use the default notes string.) If you do not specify a string parameter, VDE supplies a default notes string that depends on the module type.

See the CMS documentation for a description of the CMS notes string and its format.

/NOTIFY=(username [,username...])

Specifies users to notify of all changes to the new module. Each username parameter specifies the OpenVMS username or mail address of a user who should be notified by mail message each time the specified module is replaced into the VDE library.

Each username parameter can specify the username of a user already recorded in the VDE database, a OpenVMS mail address with one or more node names (such as NODE::SMITH), or a mail forwarding alias, or a defined logical name bound to a list of users to notify. If you specify a logical name, keep in mind that the logical name must be defined when it is later used to send notification messages. It should thus be a group or system logical name or a logical name that is in some other way defined for all users of the VDE library.

If you specify only one username parameter, you may omit the surrounding parentheses.

/POSITION=column-number

Specifies the default column number in which CMS notes are to be placed when this source module is retrieved with a FETCH or RESERVE command. The column number must be an integer in the range 1 to 511. If this qualifier is omitted, the default column number is 81. This qualifier has no effect unless notes are enabled with the /NOTES qualifier on the CREATE MODULE command or on the FETCH or RESERVE command.

See the CMS documentation for a description of CMS notes and how notes are formatted at the ends of source lines.

/PROPAGATE

/NOPROPAGATE

Specifies whether automatic change propagation is allowed for this module when it is reserved and replaced into the library. /PROPAGATE allows automatic change propagation and /NOPROPAGATE disallows change propagation. If change propagation is disallowed, VDE automatically inhibits change propagation when the module is reserved or replaced as if the /NOPROPAGATE qualifier had been specified for the RESERVE or REPLACE command. If you omit both qualifiers, the value of the facility's nopopulate attribute is used to set the new module's propogate attribute.

/REMARK="string"

Specifies a remark string to be stored for the new module. The quoted remark string, which can be up to 132 characters long, may contain any explanatory remark about the new module that you want stored in the VDE database. Typically the remark describes the purpose or content of the module.

Although this qualifier is required, you can specify an empty remark string. If you do not specify the /REMARK qualifier, VDE prompts you for a remark string.

/REVIEWER=(username [,username...])

Specifies reviewers for all changes to the new module. Each username parameter specifies the OpenVMS username of a user who should review all changes to the specified module. The user must already be recorded in the VDE database. When a change to the module is replaced into the VDE library, VDE notifies the user of the change by mail message. If the replacement is queued, the user should then review the queued replacement before it is performed. If the replacement is immediate, VDE notifies the user of the new module generation that was created, and the user may then inspect that generation.

If you specify only one username parameter, you may omit the surrounding parentheses.

/SESSION[=session-name]

Sessions are used to logically group a set of module reservations together, typically to group all modules related to a particular source code alteration or enhancement together. It allows all component modules reserved to be treated as a single entity for subsequent replacement operations. A session also allows additional modules to be reserved and incorporated into an existing session at a later time.

If the new module is being created such that the initial generation will be created by a subsequent replacement, /SESSION specifies that VDE should add the new module reservation to the reservation session given by the session-name parameter.

If no session with the specified session-name session name currently exists, VDE will create a new reservation session under the specified session name and will incorporate the module reservation(s) into it.

If the session-name parameter is omitted, VDE generates a unique session name, creates a new session by that name, and adds the module reservation to it.

If the /SESSION qualifier is omitted on the CREATE MODULE command, VDE will reserve the module (as expected), and will not add the new module reservation to any session.

Sessions can be manipulated via the REPLACE, RESERVE, UNRESERVE, MODIFY SESSION, MODIFY RESERVATION, CREATE MODULE, and CANCEL SESSION commands. And modules created by CREATE MODULE (on a queued-replacement stream) and reserved via RESERVE can be combined into the same session.

/STREAM=stream-name

Specifies that the module be reserved for the stream given by the stream-name parameter or that the initial generation of the module be inserted into that stream. If neither /INPUT nor /FROM_DIRECTORY is specified, the /STREAM qualifier causes VDE to mark the module as reserved for the specified stream. If the /INPUT or /FROM_DIRECTORY qualifier is specified, /STREAM causes the the initial generation of the new module to become the latest generation of the module for the specified stream and all its successor streams.

If the /STREAM qualifier is omitted, the module is reserved for or inserted into your current default stream.

Examples

VDE„ CREATE MODULE STGCVT.FOR /STREAM=FOO /REMARK="String conversion routines"
%VDE-I-RESERVED, generation [CODE]STGCVT.FOR reserved from stream FOO
%VDE-I-MUSTREPL, you must replace the new module to create its first generation
%VDE-I-MODADDED, module [CODE]STGCVT.FOR added to the database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

This example creates a new source module called STGCVT.FOR. The module is created in the current default facility, facility CODE, and is reserved from the specified stream FOO. A subsequent REPLACE command (not shown) is needed to create the first generation of the module.

VDE„ CREATE MODULE/NOLOG STGCVT.FOR /STREAM=FOO /REMARK="String conversion routines"
VDE„
      

Here the same module is created as in the previous example, but the /NOLOG qualifier suppresses the log messages.

VDE„ CREATE MODULE STGCVT.FOR /NOLOG /INPUT=[MYDIR]FOO.FOR -
VDE„                          /REMARK="String conversion routines"
VDE„
      

In this example, the /INPUT qualifier causes the command to create the initial generation of the module from file [MYDIR]FOO.FOR. In this case, the module is not marked as reserved.

VDE„ CREATE MODULE [CODE]STGCVT.FOR /REMARK="String routines", -
_VDE„              [ACCTNG]SALES.COB /REMARK="Sales accounting"
%VDE-I-RESERVED, generation [CODE]STGCVT.FOR reserved from stream MAIN
%VDE-I-MUSTREPL, you must replace the new module to create its first generation
%VDE-I-MODADDED, module [CODE]STGCVT.FOR added to the database
%VDE-I-RESERVED, generation [ACCTNG]SALES.COB reserved from stream MAIN
%VDE-I-MUSTREPL, you must replace the new module to create its first generation
%VDE-I-MODADDED, module [ACCTNG]SALES.COB added to the database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

This example creates two new source modules, one in facility CODE and one in facility ACCTNG. Each module has its own remark string. The modules are reserved in the user's default stream, stream MAIN.

VDE„ SET STREAM MAIN
VDE„ SET FACILITY CODE
VDE„ CREATE MODULE/FROM_DIRECTORY=[MYDIR.SOURCES]/REMARK=""
%VDE-I-GENINSERT, generation [CODE]A.REQ;1(1) inserted into stream MAIN
%VDE-I-MODADDED, module [CODE]A.REQ added to the database
%VDE-I-GENINSERT, generation [CODE]B.REQ;1(1) inserted into stream MAIN
%VDE-I-MODADDED, module [CODE]B.REQ added to the database
%VDE-I-GENINSERT, generation [CODE]C.B32;1(1) inserted into stream MAIN
%VDE-I-MODADDED, module [CODE]C.B32 added to the database
%VDE-I-GENINSERT, generation [CODE]D.B32;1(1) inserted into stream MAIN
%VDE-I-MODADDED, module [CODE]D.B32 added to the database
%VDE-I-GENINSERT, generation [CODE]E.B32;1(1) inserted into stream MAIN
%VDE-I-MODADDED, module [CODE]E.B32 added to the database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

This example uses the /FROM_DIRECTORY qualifier to create modules for all files in a given directory. The SET STREAM command makes stream MAIN the default stream and the SET FACILITY command makes facility CODE the default facility. The CREATE MODULE command reads all files in directory [MYDIR.SOURCES] and creates a module in facility CODE for each such file. VDE creates the initial generation of each module and inserts that generation into the default stream (stream MAIN) and all successor streams. (No successor streams are defined in this example.) The log messages confirm that the initial generations have been inserted into the appropriate streams and that the modules have been added to the database.