Créer une fonction dans un script Batch

Les fichiers Batch ne déclarent pas les fonctions au moyen d’un mot-clé de déclaration distinct. Une sous-routine réutilisable est une étiquette, appelée avec CALL ; CALL exécute les commandes qui suivent cette étiquette, puis reprend à la commande située après l’appel. Ces exemples utilisent la syntaxe de Windows CMD et doivent être exécutés dans un fichier .bat ou .cmd sous Windows.

Fonctionnement des fonctions Batch

En Batch, une « fonction » est généralement appelée une sous-routine. Son étiquette désigne le point d’entrée, tandis que CALL :label lui transfère le contrôle et mémorise un point de retour. Une étiquette ne crée pas à elle seule une portée distincte et ne provoque pas de retour automatique. Utilisez EXIT /B dans la sous-routine pour revenir à son appelant ; sans retour explicite, l’exécution peut se poursuivre dans les étiquettes et commandes suivantes. EXIT /B quitte le script Batch en cours lorsqu’il n’est pas appelé comme sous-routine.

Définir et appeler une fonction Batch

Placez l’appel avant l’étiquette, puis terminez le corps principal par GOTO :EOF pour éviter que l’exécution ne continue directement dans la sous-routine. Dans le script généré, la sous-routine affiche un message de bienvenue, puis revient à l’appelant.

Pour afficher un petit script Windows CMD sans laisser entendre que CMD a été exécuté ici, lancez ce script Python. Il affiche le code source Batch ; enregistrez cette sortie dans un fichier .bat ou .cmd, puis exécutez-le dans Windows CMD.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

print('''@echo off
call :greet "Ada"
echo Back in the main script.
goto :eof

:greet
echo Hello, %~1!
exit /b 0''')

@echo off
call :greet "Ada"
echo Back in the main script.
goto :eof

:greet
echo Hello, %~1!
exit /b 0

Le script généré est destiné à Windows CMD ; Python affiche le code source sans l’exécuter. GOTO :EOF termine le flux principal, et EXIT /B 0 renvoie un état de réussite depuis l’étiquette appelée. 0 est le code de réussite conventionnel ; un code différent de zéro peut signaler un échec à l’appelant.

Transmettre des arguments à une fonction Batch

Les arguments suivent l’étiquette dans la commande CALL et sont séparés par des espaces. Dans la sous-routine, %1 désigne le premier argument, %2 le deuxième, et ainsi de suite. Préférez %~1 pour récupérer le premier argument sans ses éventuels guillemets environnants ; le tilde ne rend pas la valeur sûre à insérer dans toutes les commandes. Mettez les valeurs entre guillemets lorsque vous les utilisez comme chemins ou comme texte.

Cet exemple Python affiche un script Batch complet qui transmet un argument contenant une espace ; enregistrez le code affiché dans un fichier .bat ou .cmd pour l’exécuter dans Windows CMD. La sous-routine :show lit la valeur sous la forme %~1.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

print("""@echo off
call :show "Ada Lovelace"
goto :eof

:show
echo Name: %~1
exit /b 0""")

@echo off
call :show "Ada Lovelace"
goto :eof

:show
echo Name: %~1
exit /b 0

Conservez le développement des arguments dans des comparaisons entre guillemets ou des affectations SET entre guillemets lorsque la valeur peut contenir des espaces ou des métacaractères de commande. L’analyse Batch comporte plusieurs phases de développement ; les valeurs complexes contenant, par exemple, %, & ou | demandent donc une attention particulière.

Valeurs de retour et codes de sortie

Batch ne possède pas d’emplacement intégré pour la valeur de retour d’une fonction. Une méthode courante consiste à placer le résultat dans une variable d’environnement et à utiliser séparément le code de sortie de la sous-routine pour indiquer une réussite ou un échec. Cet exemple Python affiche un script Batch complet qui appelle une sous-routine à deux arguments, vérifie son état immédiatement après CALL et lit la variable de résultat en cas de réussite. Enregistrez le code affiché dans un fichier .bat ou .cmd pour l’exécuter dans Windows CMD.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

print("""@echo off
setlocal EnableExtensions
call :add 5 10
if errorlevel 1 goto add_failed
echo Sum: %sum%
goto :eof

:add_failed
echo Addition failed.
goto :eof

:add
if "%~1"=="" exit /b 1
if "%~2"=="" exit /b 1
setlocal
set /a "_sum=%~1 + %~2"
endlocal & set "sum=%_sum%"
exit /b 0""")

@echo off
setlocal EnableExtensions
call :add 5 10
if errorlevel 1 goto add_failed
echo Sum: %sum%
goto :eof

:add_failed
echo Addition failed.
goto :eof

:add
if "%~1"=="" exit /b 1
if "%~2"=="" exit /b 1
setlocal
set /a "_sum=%~1 + %~2"
endlocal & set "sum=%_sum%"
exit /b 0

L’étiquette lit les valeurs positionnelles sous la forme %~1 et %~2. SETLOCAL conserve la variable temporaire _sum dans la portée locale ; sur la même ligne de commande, CMD développe %_sum% avant l’exécution de ENDLOCAL, puis affecte cette valeur à la variable sum de l’appelant. Gardez ENDLOCAL & SET sur la même ligne. Cet exemple attend des arguments entiers ; les arguments manquants renvoient l’état 1, tandis qu’une addition terminée renvoie l’état 0.

Gérer les erreurs dans une fonction Batch

Vérifiez les entrées requises au début de la sous-routine et renvoyez un état différent de zéro si elles manquent. Cet exemple Python affiche un script Batch complet qui appelle la même étiquette de validation avec une entrée manquante puis présente ; chaque vérification if errorlevel 1 suit immédiatement son appel CALL. Enregistrez le code affiché dans un fichier .bat ou .cmd pour l’exécuter dans Windows CMD.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

print("""@echo off
call :require_value
if errorlevel 1 (
    echo Missing input: rejected with status 1.
) else (
    echo Missing input: accepted.
)

call :require_value "report.txt"
if errorlevel 1 (
    echo Valid input: rejected.
) else (
    echo Valid input: accepted with status 0.
)
goto :eof

:require_value
if "%~1"=="" exit /b 1
exit /b 0""")

@echo off
call :require_value
if errorlevel 1 (
    echo Missing input: rejected with status 1.
) else (
    echo Missing input: accepted.
)

call :require_value "report.txt"
if errorlevel 1 (
    echo Valid input: rejected.
) else (
    echo Valid input: accepted with status 0.
)
goto :eof

:require_value
if "%~1"=="" exit /b 1
exit /b 0

Le premier appel suit la branche d’échec, car la valeur requise est absente ; le second suit la branche de réussite. if errorlevel 1 signifie que le niveau d’erreur actuel est supérieur ou égal à 1 ; si le code exact importe, vérifiez les codes plus élevés en ordre décroissant. Avec un argument valide, la sous-routine peut effectuer son travail et terminer par EXIT /B 0.

Pour revenir d’une sous-routine, utilisez EXIT /B plutôt que EXIT : EXIT ferme la session CMD, tandis que EXIT /B revient du contexte Batch en cours. Si une commande CALL cible une étiquette inexistante, CMD signale une erreur ; écrire les étiquettes de façon cohérente et associer clairement chaque appel à son étiquette facilite le diagnostic. Les exemples Python affichent le code source Batch sans l’exécuter ; lancez les scripts enregistrés dans Windows CMD pour observer leur comportement Batch.