Details: Creating a vendor block

Create a new ST-object within the project: For instance, open the context menu, select New and ST-Object . In the dialog, enter any object name. This instruction uses the name TestVendor for the ST-object.

Copy the following code, and paste it into the opened editor for the ST-object. Do not save the pasted code yet.

{CustomImplementation}
NAMESPACE com.oem1.lib1
  FUNCTION TestVendor01
    { ImplementationProperties (functionHasCFile; ) }
    VAR_INPUT
      in1 : INT;
      in2 : BOOL;
    END_VAR
    VAR_OUTPUT
      out1 : BOOL;
    END_VAR
  END_FUNCTION
END_NAMESPACE

Explanation of the statements necessary for the vendor block:

Replacement or additional statement

Purpose

{CustomImplementation}

This statement identifies the block as vendor block to be used for a library.
Due to this statement , vendor blocks in C-code are also called CustomImpl blocks in the everyday language of logi.cals.

FUNCTION TestVendor01
{ ImplementationProperties (functionHasCFile; ) }

functionHasCFile is an optional keyword. This keyword is only required, if your vendor block uses your own C-code. The instruction assumes that this is the case.
The keywords would not be required, if a vendor block is realized by macros in the H-file only.

The statement { ImplementationProperties ( ) } is a container for other keywords as well. See " Properties for implementing vendor blocks " for those possibilities.

Adjust the code as requested.
Mind the following:
- logi.cals recommends the usage of a namespace as specified in the above code, just adjust the name com.oem1.lib1 according to your needs. Always specify the namespace before you save the ST-object because the namespace is part of the C structure and function name.
- If you want to create a vendor function block instead of a vendor function, change the keyword FUNCTION to FUNCTION_BLOCK and the keyword END_FUNCTION to END_FUNCTION_BLOCK.
- Adjust the rest of the code so that it fits your need: For example, change the names of the function or function block, of the inputs and of the outputs. Or change the data type of the inputs and of the outputs. Or add new inputs and outputs as known from the ST-editor.
  logi.cals recommends you to declare all types of variables within the interface – in particular, if the values of the variables should be kept for the block from one execution of the application to the next one. So you will avoid problems that might occur otherwise when updating the changed application by using the resource manager (also known as reloading the application).
  
  If you do declare variables just within a C-file and some belated changes of the block logic are needed, logi.cals recommends you to create a new block containing the changed logic – instead of actually changing the block. Subsequently, it will be possible to use the r esource manager for updating the changed application.
  logi.CAD 3 does not prevent the change of a block with variables only contained in the C-file. If you make such changes and use the resource manager to update the changed application, unexpected errors might occur. For example, the application might be executed wrongly or it might be terminated, the PLC might even be terminated. In such cases, best practice is to build the application anew and then to load it onto the PLC.

Only when the code is complete, save the ST-object.
If you have already saved the ST-object before the completion of the code, it is likely that the object is not in sync with the generated files anymore. Example: You have declared a CustomImplementation function with a data type as the return value of this function, you saved the ST-object and then you used the data type in the function and you saved this change. In this case, the 1st saving action creates the C-/H-files with the implementation stub, while the 2nd saving action does not update the C-/H-files with the implementation stub. In this case, you must rename the automatically generated files to another unique name (if you have already entered your code in these C-/H-files) or delete these files (if you have not entered any code in these C-/H-files yet). Then, save the ST-object again to make sure that the generated files contain the correct implementation stubs. If you renamed the C-/H-files that were generated: Transfer your code to the newly generated C-/H-files and delete the renamed C-/H-files.

Result (when the implementation stubs have not been generated yet): logi.CAD 3 generates 2 files with the required implementation stubs.

File	Name of file for above code	Details
the C (source) file	`lcfu___COM.OEM1.LIB1.TESTVENDOR01.c`	This file is only auto-generated, if `functionHasCFile` has been specified.
the H-file	`lcfu___COM.OEM1.LIB1.TESTVENDOR01.h`	If you are interested in the basic structure of an H-file, read the article "The structure of the needed H-file".

These files are located in the newly created folder src-code on the same level as the ST-object. Mind the capital letters of the POU names within the file names. This is important, if you are using the created library with the vendor block on a Linux computer. If you are using the library just on a Windows computer, the POU names with lower letters (in the file names) would be of no consequence.
If the folder src-code is not visible, the value for the configuration variable lc3.src_code.filter.enable has to be changed. Contact your logi.CAD 3 administrator for this configuration change.

Close the editor for the ST-object.
Recommended: C lean the project.
Start to create the required code: Enter the C-code in the C-file and/or enter the macros in the H-file.
Observe the following:
1. If you are declaring variables with a →generic data type within the interface of the vendor block, you must also adapt the auto-generated implementation stubs and/or use the statement { ImplementationProperties ( ) } and some of its definitions within the interface.
2. If you are calling f unctions of a library in the C-code of the vendor block, you must use the pragma { FunctionReferences } within the interface.
3. Use POU-unique names (when possible, project- and POU-unique) for all C-identifiers that are available in a global namespace. Details on the reason for this can be found under "The dos and don'ts when working", section "When creating blocks with C-code".

The following articles will assist you in creating the H-file and using the statements/pragmas in the interface:

- "The structure of the needed H-file"
- " Properties for implementing vendor blocks "

See "Creating your library using the vendor block", if you want to deploy the vendor block along with a library.