USE [Elyse_DB]
GO
/****** Object:  StoredProcedure [controlling].[usp_INS_file_group_name]    Script Date: Mon 07-09-2026 7:26:40 PM ******/
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
-- =============================================
-- Author:		Silkwood Software
-- Create date: 26-12-2023
-- Description:	Initial creation
-- Creates a new file group name
-- by inserting a record into file_group_names.
-- Input is the paramters for a file group name:
-- mnemonic, name, description.  
-- Output is a status message, a transaction status and the id of the new record.  
/*
COPYRIGHT NOTICE
This database schema and stored procedures are protected by copyright.
Copyright.  Silkwood Software Pty. Ltd. 2023
*/

-- =============================================
/**
* Creates a new file group name record.
* 
* **Acceptable Inputs:**
*
* - @mnemonic nvarchar(10)
* - @attribute_name nvarchar(50): Must be a non-null and non-empty valid identifier.
* - @description nvarchar(max)
*
* **Return Values:**
*
* - @newrecordid bigint: ID of the new record
* - @message nvarchar(1000) OUTPUT: Descriptive status message of the procedure's execution.
* - @transaction_status nchar(50) OUTPUT: Indicates the transaction status ('Good', 'Bad', or default 'Transaction not attempted').
*
* **Error and Exception Conditions:**
*
* - User Role Validation Fail: Returns 'No Permission' message.
* - Data Validation Fail: Returns messages for missing, invalid or duplicate @attr_name.
*
* **Side Effects:**
*
* - Adds a record in 'xref.file_group_names' table if all conditions are met.
*
* **Preconditions:**
*
* - The user executing the procedure must have the 'Controller' role.
* - @attribute_name must be provided and valid.
* - There must not be an existing record matching @attribute_name.
*
* **Postconditions:**
* - The procedure returns status messages indicating the outcome of the operation.
*
*/
-- =========================================================
CREATE PROCEDURE [controlling].[usp_INS_file_group_name] 

	 @mnemonic nvarchar(10)           = NULL,
	 @attribute_name nvarchar(50),
	 @description nvarchar(max)       = NULL,
	 @message nvarchar(1000)          = '' OUTPUT,
	 @transaction_status nvarchar(50) = NULL OUTPUT,
	 @newrecordid bigint              = NULL OUTPUT
AS
BEGIN
	-- SET NOCOUNT ON added to prevent extra result sets from
	-- interfering with SELECT statements.
	SET NOCOUNT ON;

  DECLARE 

	    @connectedusersid varbinary(100)        = SUSER_SID(ORIGINAL_LOGIN()),   -- The SID of the connected user
	    @username nvarchar(150)                 = ORIGINAL_LOGIN(),     -- The username 
		@userauthentication_status nchar(10)    = 'Fail', -- The outcome of the authentication check of the user 
	    @validationmessage nvarchar(200)        = '', -- Communicates that the transaction failed due to data validation
        @tempmessage nvarchar(300)              = '',
		@tempvalidationstatus nchar(10)         = '',		
		@transaction_ready nchar(10)            = 'Ready',
		@data_validation_status nchar(10)       = 'Pass';

  -- Parameters which have been initialised at declaration but not explicitly set might be output as null to calling functions.
  SET @transaction_status = 'Transaction not attempted';  


-- Connected user authentication
  -- Authenticate the connected user for the role
  EXEC [internal].[usp_AUTHENTICATE_user_role] 
        @role_to_check = 'Controller',
		@user_authentication_result = @userauthentication_status OUTPUT;
  IF @userauthentication_status = 'Fail'
    BEGIN  -- The user does not have permission for this action
		SET @transaction_ready      = 'Fail';
	    EXEC internal.usp_SEL_message 
            @message_id   = 'NoPermission', 
			@message_text = @tempmessage OUTPUT;
	    IF (@tempmessage IS NOT NULL) 
  	       SET @message = CONCAT_WS(' | ', @message, ISNULL(@username, ''), '  ', @tempmessage);
	    ELSE 
		   SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on NoPermission. ');
	END

  IF @userauthentication_status = 'Pass' -- Don't do anything if the user is not authorised.
    BEGIN
	  -- Data validation
	  -- Attribute name check
		IF @attribute_name = ''
		   SET @attribute_name = NULL;
		-- Attribute name must be unique
		IF EXISTS (SELECT attr_name 
		 			FROM xref.file_group_names 
					WHERE attr_name = @attribute_name) 
			BEGIN
				EXEC internal.usp_SEL_message 
					@message_id   = 'NameNotUnique', 
					@message_text = @tempmessage OUTPUT;
				IF (@tempmessage IS NOT NULL) 
  				SET @message = CONCAT(@message, ISNULL(LEFT(@attribute_name, 10), ''), '... | ', @tempmessage);
				ELSE 
					SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on NameNotUnique');
				SET @data_validation_status = 'Fail';
				SET @transaction_ready      = 'Fail';
			END

	  -- Perform generic data validation checks.  (Does not require access to the table.) 
		EXEC internal.usp_VALIDATE_mnem_name_descr
			@mnem             = @mnemonic,
			@attr_name        = @attribute_name,
			@descr            = @description,
			@data_valn_status = @tempvalidationstatus OUTPUT,
			@messg            = @validationmessage OUTPUT;
		IF @tempvalidationstatus = 'Fail'
			BEGIN
				SET @transaction_ready      = 'Fail';
				SET @data_validation_status = 'Fail';
				SET @message = CONCAT_WS(' | ', @message, @validationmessage);
			END

		-- Output the data validation status failed message
		IF @data_validation_status = 'Fail'
		BEGIN
			EXEC internal.usp_SEL_message 
				@message_id   = 'FailedDataValidation', 
				@message_text = @tempmessage OUTPUT;
			IF (@tempmessage IS NOT NULL) 
				SET @message = CONCAT_WS(' | ', @message, @tempmessage);
			ELSE 
				SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on FailedDataValidation.');
		END
		-- End data validation
    END -- End user authentication = Pass
 
-- Execute the insert query
  IF @transaction_ready = 'Ready'
	BEGIN
	  BEGIN TRY
	     INSERT INTO xref.file_group_names 
		             (mnem,                   attr_name,              descr)
		      VALUES (ISNULL(@mnemonic, ''), @attribute_name, ISNULL(@description, ''));
            SET @newrecordid = SCOPE_IDENTITY();			  
         EXEC internal.usp_SEL_message 
              @message_id   = 'Success', 
              @message_text = @tempmessage OUTPUT;
  	     IF (@tempmessage IS NOT NULL) 
	        SET @message = CONCAT_WS(' | ', @message, @tempmessage);
	     ELSE 
		      SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on Success.');
		 SET @transaction_status = 'Good';
   	  END TRY
	  BEGIN CATCH

	     IF XACT_STATE() <> 0
            ROLLBACK TRANSACTION;

	     SET @transaction_status = 'Bad';
         EXEC internal.usp_SEL_message 
              @message_id   = 'InsertError', 
              @message_text = @tempmessage OUTPUT;
		 IF (@tempmessage IS NOT NULL) 
		    SET @message = CONCAT(@message, @tempmessage, ' | ', 
		    CONVERT(nvarchar(10),ERROR_NUMBER()), ' | ', ERROR_MESSAGE());
		 ELSE 
		      SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on InsertError.');
	  END CATCH
    END

	  

END
GO